# Sapiens2

    
        
        
    

## Visão geral

O modelo Sapiens2 foi proposto em [Sapiens2](https://huggingface.co/papers/2604.21681) por Rawal Khirodkar, He Wen, Julieta Martinez, Yuan Dong, Zhaoen Su, Shunsuke Saito. O Sapiens2 é uma família de vision transformers de alta resolução pré-treinados em ~1 bilhão de imagens humanas curadas, projetado para tarefas de visão computacional centradas em humanos, incluindo estimativa de pose, segmentação de partes do corpo, estimativa de normais de superfície e estimativa de pointmap.

Você pode encontrar todos os checkpoints originais do Sapiens2 na coleção [Sapiens2](https://huggingface.co/collections/facebook/sapiens2).

O resumo do artigo é o seguinte:

*Apresentamos o Sapiens2, uma família de transformers de alta resolução para visão centrada em humanos, com foco em generalização, versatilidade e saídas de alta fidelidade. Fazemos o pré-treinamento em cerca de 1 bilhão de imagens humanas de alta qualidade e curadas, com anotações de tarefas aprimoradas, e combinamos a reconstrução de imagens mascaradas com objetivos contrastivos autodestilados para aprender tanto recursos de baixo nível quanto recursos semânticos. Nossos modelos variam de 0,4B a 5B parâmetros e são treinados na resolução nativa de 1K, com variantes hierárquicas de 4K para raciocínio espacial estendido. O Sapiens2 alcança melhorias substanciais em relação ao seu antecessor: +4 mAP na estimativa de pose, +24,3 mIoU na segmentação de partes do corpo e redução de 45,6% no erro na estimativa de normais, além de se estender a novas tarefas, como a estimativa de pointmap e albedo. O código está publicamente disponível.*

Dicas:

- Sapiens2 usa Rotary Position Embeddings (RoPE) e suporta resoluções de entrada arbitrárias. O processador de imagem padrão redimensiona as imagens para 1024×768 (altura×largura).
- O modelo usa Grouped Query Attention (GQA) para as camadas intermediárias e atenção multi-head completa para as primeiras e últimas 8 camadas.
- Os tokens de registro (8 por padrão) reduzem artefatos de norma elevada nos tokens de patch, resultando em mapas de atenção mais limpos e melhor desempenho em tarefas de predição densa.

Este modelo foi contribuído por [guarin](https://huggingface.co/guarin). O código original pode ser encontrado [aqui](https://github.com/facebookresearch/sapiens2).

## Exemplos de uso

O exemplo abaixo mostra como obter o token CLS (embedding da imagem inteira) com [Sapiens2Model](/docs/transformers/main/pt/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/main/pt/model_doc/sapiens2#transformers.Sapiens2Backbone) expõe tokens de patch já redimensionados para dimensões espaciais e tokens CLS diretamente no objeto de saída.

```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]
```

O exemplo abaixo mostra como estimar normais de superfície com [Sapiens2ForNormalEstimation](/docs/transformers/main/pt/model_doc/sapiens2#transformers.Sapiens2ForNormalEstimation). As normais de saída são brutas (não normalizadas); use `post_process_normal_estimation` para redimensioná-las e normalizá-las em 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]
```

O exemplo abaixo mostra como estimar coordenadas 3D por pixel com [Sapiens2ForPointmapEstimation](/docs/transformers/main/pt/model_doc/sapiens2#transformers.Sapiens2ForPointmapEstimation). Use `post_process_pointmap_estimation` para remover o padding de pré-processamento, redimensionar para o tamanho original da imagem e aplicar a escala de distância focal prevista.

```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]
```

O exemplo abaixo mostra como executar a estimativa de pose com [Sapiens2ForPoseEstimation](/docs/transformers/main/pt/model_doc/sapiens2#transformers.Sapiens2ForPoseEstimation). O modelo prevê heatmaps por ponto-chave; use `post_process_pose_estimation` para decodificá-los de volta para as coordenadas dos pontos-chave no espaço da imagem. É necessário `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)
```

Aumentação por inversão horizontal (aumentação no momento de teste) melhora a precisão dos pontos-chave ao fazer a média das previsões da imagem original e da imagem espelhada. Passe `flip_pairs` — um tensor de pares `[left_keypoint, right_keypoint]` — para a segunda passagem de frente. O modelo inverte os mapas de calor de volta para a orientação original antes de retorná-los, permitindo que você faça a média diretamente de ambas as saídas.

```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"]
```

O exemplo abaixo mostra como calcular a perda de erro quadrático médio (MSE) mascarado supervisionado com [Sapiens2ForPoseEstimation](/docs/transformers/main/pt/model_doc/sapiens2#transformers.Sapiens2ForPoseEstimation) passando `labels` e `label_weights` opcionais. Isso é útil para ajuste fino usando a 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())
```

O exemplo abaixo mostra como realizar segmentação de partes do corpo com [Sapiens2ForSemanticSegmentation](/docs/transformers/main/pt/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]
```

O exemplo abaixo mostra como executar o matting de imagem com [Sapiens2ForImageMatting](/docs/transformers/main/pt/model_doc/sapiens2#transformers.Sapiens2ForImageMatting). As saídas são ativadas por sigmoid e já estão em `[0, 1]`; use `post_process_image_matting` para redimensionar e dividir em `alphas`, `foregrounds` e uma imagem `composite` opcional. A imagem composite mostra o primeiro plano sobreposto ao plano de fundo com a fórmula: `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)
```

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

**Parâmetros:**

patch_size (`Union[int, list[int], tuple[int, int]]`, *opcional*, padrão `16`) : O tamanho (resolução) de cada patch.

hidden_size (`int`, *opcional*, padrão `1024`) : Dimensão das representações ocultas.

intermediate_size (`int`, *opcional*, padrão `4096`) : Dimensão das representações do MLP.

num_hidden_layers (`int`, *opcional*, padrão `24`) : Número de camadas ocultas no decodificador do Transformer.

num_attention_heads (`int`, *opcional*, padrão `16`) : Número de cabeças de atenção para cada camada de atenção no decodificador do Transformer.

hidden_act (`str`, *opcional*, padrão `silu`) : A função de ativação não linear (função ou string) no decodificador. Por exemplo, `"gelu"`, `"relu"`, `"silu"`, etc.

attention_dropout (`Union[float, int]`, *opcional*, padrão `0.0`) : A taxa de dropout para as probabilidades de atenção.

initializer_range (`float`, *opcional*, padrão `0.02`) : O desvio padrão do truncated_normal_initializer para inicializar todas as matrizes de pesos.

rope_theta (`float`, *opcional*, padrão 100.0) : O período base dos embeddings RoPE.

image_size (`Union[int, list[int], tuple[int, int]]`, *opcional*, padrão `224`) : O tamanho (resolução) de cada imagem.

num_channels (`int`, *opcional*, padrão `3`) : O número de canais de entrada.

query_bias (`bool`, *opcional*, padrão `True`) : Se deve adicionar um viés à projeção da consulta.

key_bias (`bool`, *opcional*, padrão `False`) : Se deve adicionar um viés à projeção da chave.

value_bias (`bool`, *opcional*, padrão `True`) : Se deve adicionar um viés à projeção de valor.

proj_bias (`bool`, *opcional*, padrão `True`) : Se deve adicionar um viés à projeção de saída.

mlp_bias (`bool`, *opcional*, padrão `True`) : Se deve usar um viés nas camadas up_proj, down_proj e gate_proj das camadas MLP.

layerscale_value (`float`, *opcional*, padrão 1.0) : Valor inicial a ser usado para a escala da camada.

drop_path_rate (`Union[float, int]`, *opcional*, padrão `0.0`) : Taxa de drop path para a fusão de patches.

use_gated_mlp (`bool`, *opcional*, padrão `False`) : Se deve usar a rede neural feedforward SwiGLU.

num_register_tokens (`int`, *opcional*, padrão 0) : O número de tokens de registro.

pos_embed_shift (`float`, *opcional*) : Quantidade para deslocar aleatoriamente as coordenadas do embedding de posição em [-shift, shift], aplicado apenas no modo de treinamento, se não for `None`.

pos_embed_jitter (`float`, *opcional*) : Quantidade para jitter aleatório das coordenadas do embedding de posição em valor log-uniforme em [1/jitter, jitter], aplicado apenas no modo de treinamento se não for `None`.

pos_embed_rescale (`float`, *opcional*, padrão 2.0) : Quantidade para reescalar aleatoriamente as coordenadas do embedding de posição em um valor log-uniforme em [1/rescale, rescale], aplicado apenas no modo de treinamento se não for `None`.

reshape_hidden_states (`bool`, *opcional*, padrão `True`) : Se deve redimensionar os estados ocultos para dimensões espaciais quando usado como backbone.

use_mask_token (`bool`, *opcional*, padrão `False`) : Se deve usar um token de máscara nos embeddings (necessário para o pré-treinamento de modelagem de imagem mascarada).

rms_norm_eps (`float`, *opcional*, padrão 1e-6) : Epsilon para as camadas de normalização RMS.

normalize_backbone_outputs (`bool`, *opcional*, padrão `True`) : Se deve aplicar RMSNorm às saídas `feature_maps` e `cls_tokens` do backbone antes de retorná-las da forward pass. Aplica-se apenas quando o modelo é usado como backbone.

use_qk_norm (`bool`, *opcional*, padrão `True`) : Se deve aplicar RMSNorm às queries e keys antes do RoPE nas camadas de atenção.

num_key_value_heads_per_layer (`list[int]`, *opcional*) : Número de cabeças de chave/valor para cada camada do transformer. Definir o valor de uma camada igual a `num_attention_heads` resulta em atenção multi-cabeça completa; um valor menor resulta em atenção de consulta agrupada. O padrão é `num_attention_heads` para as primeiras `num_first_full_attention_layers` e as últimas `num_last_full_attention_layers` camadas e `num_key_value_attention_heads` para todas as outras camadas.

num_key_value_attention_heads (`int`, *opcional*, padrão `8`) : Número de cabeças de chave/valor para camadas que usam atenção de consulta agrupada quando `num_key_value_heads_per_layer` não está definido. Ignorado quando `num_key_value_heads_per_layer` está definido.

num_first_full_attention_layers (`int`, *opcional*, padrão 8) : Número de camadas iniciais do transformer que usam atenção multi-head completa. Usado apenas quando `num_key_value_heads_per_layer` é `None`.

num_last_full_attention_layers (`int`, *opcional*, padrão 8) : Número de camadas finais de transformer que usam atenção multi-head completa. Usado apenas quando `num_key_value_heads_per_layer` é `None`.

semantic_loss_ignore_index (`int`, *opcional*, padrão 255) : Índice de rótulo ignorado ao calcular a perda de segmentação.

flip_pairs (`list[list[int]]`, *opcional*) : Pares de índices de pontos-chave que são espelhados horizontalmente (por exemplo, orelha esquerda ↔ orelha direita). Cada par é uma lista de dois elementos `[left_index, right_index]`. Usado para aumento de dados por inversão horizontal no momento do teste em estimativa de pose: passe esses pares para a segunda chamada de forward para que o modelo inverta os mapas de calor de volta antes de retorná-los.

head_config (`Sapiens2HeadConfig`, *opcional*) : Configuração para o cabeçalho de decodificação. Consulte [Sapiens2HeadConfig](/docs/transformers/main/pt/model_doc/sapiens2#transformers.Sapiens2HeadConfig) para as opções disponíveis.

Esta é a classe de configuração para armazenar a configuração de um Sapiens2Model. Ela é usada para instanciar um modelo Sapiens2 de acordo com os argumentos especificados, definindo a arquitetura do modelo. Instanciar uma configuração com os padrões resultará em uma configuração semelhante à do [facebook/sapiens2-pretrain-0.4b](https://huggingface.co/facebook/sapiens2-pretrain-0.4b)

Os objetos de configuração herdam de [PreTrainedConfig](/docs/transformers/main/pt/main_classes/configuration#transformers.PreTrainedConfig) e podem ser usados para controlar as saídas do modelo. Leia a documentação de [PreTrainedConfig](/docs/transformers/main/pt/main_classes/configuration#transformers.PreTrainedConfig) para mais informações.

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

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

**Parâmetros:**

upsample_out_channels (`list[int]`, *opcional*) : Contagem de canais de saída para cada bloco de upsample. O primeiro bloco recebe `hidden_size` canais como entrada; os blocos subsequentes usam a saída anterior.

upsample_kernel_sizes (`list[int]`, *opcional*) : Tamanho do kernel para cada bloco de upsample. Preenchido automaticamente com `[4, ...]` quando `upsample_out_channels` está definido, mas este é `None`. Deve ter o mesmo comprimento que `upsample_out_channels`.

upsample_kernel_size (`int`, padrão 4) : Tamanho padrão do kernel para blocos de upsample quando `upsample_kernel_sizes` não está definido.

use_pixel_shuffle (`bool`, *opcional*) : Se a cabeça de upsample usa upsample por pixel-shuffle em vez de convoluções transpostas. Quando `None` (padrão), a cabeça usa convoluções transpostas.

conv_out_channels (`list[int]`, *opcional*) : Contagens de canais de saída para as camadas de convolução de refinamento que seguem os blocos de upsample.

conv_kernel_sizes (`list[int]`, *opcional*) : Tamanho do kernel para cada camada de convolução de refinamento. Preenchido automaticamente com `[1, ...]` quando `conv_out_channels` está definido, mas este é `None`. Deve ter o mesmo comprimento que `conv_out_channels`.

conv_kernel_size (`int`, padrão 1) : Tamanho padrão do kernel para camadas conv quando `conv_kernel_sizes` não está definido.

scale_conv_out_channels (`list[int]`, *opcional*) : Contagens de canais de saída para as camadas de convolução com stride-2 usadas para prever a escala de distância focal. Quando `None` (padrão), nenhum ramo de escala é construído.

scale_conv_kernel_sizes (`list[int]`, *opcional*) : Tamanho do kernel para cada camada de convolução de escala. Preenchido automaticamente com `[1, ...]` quando `scale_conv_out_channels` está definido, mas este é `None`. Deve ter o mesmo comprimento que `scale_conv_out_channels`.

scale_conv_kernel_size (`int`, padrão 1) : Tamanho padrão do kernel para as camadas de convolução de escala quando `scale_conv_kernel_sizes` não está definido.

scale_final_input_size (`int`, *opcional*) : Tamanho da característica achatada passado para o MLP de escala. Quando `None` (padrão), é inferido automaticamente a partir de `image_size` e `patch_size` no [Sapiens2Config](/docs/transformers/main/pt/model_doc/sapiens2#transformers.Sapiens2Config) pai.

scale_final_hidden_sizes (`list[int]`, *opcional*) : Tamanhos das camadas ocultas do MLP que mapeia os recursos de escala achatados para a saída escalar de escala. Quando `None` (padrão), nenhum ramo de escala é construído.

Esta é a classe de configuração para armazenar a configuração de um Sapiens2Model. Ela é usada para instanciar um modelo Sapiens2 de acordo com os argumentos especificados, definindo a arquitetura do modelo. Instanciar uma configuração com os padrões resultará em uma configuração semelhante à do [facebook/sapiens2-seg-0.4b](https://huggingface.co/facebook/sapiens2-seg-0.4b)

Os objetos de configuração herdam de [PreTrainedConfig](/docs/transformers/main/pt/main_classes/configuration#transformers.PreTrainedConfig) e podem ser usados para controlar as saídas do modelo. Leia a documentação de [PreTrainedConfig](/docs/transformers/main/pt/main_classes/configuration#transformers.PreTrainedConfig) para mais informações.

## Sapiens2ImageProcessor[[transformers.Sapiens2ImageProcessor]]

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

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

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

**Parâmetros:**

do_convert_rgb (`bool`, *kwargs*, *opcional*) : Se deve converter a imagem para RGB.

do_resize (`bool`, *kwargs*, *opcional*, padrão `True`) : Se deve redimensionar a imagem.

size (`Annotated[int | list[int] | tuple[int, ...] | dict[str, int] | None, None]`, *kwargs*, padrão `{'height' : 1024, 'width': 768}`): Descreve as dimensões de entrada máximas para o modelo.

default_to_square (`bool`, *kwargs*, *opcional*, padrão `True`) : Se deve usar uma imagem quadrada por padrão ao redimensionar, caso o tamanho seja um inteiro.

crop_size (`Annotated[int | list[int] | tuple[int, ...] | dict[str, int] | None, None]`, *kwargs*, padrão `{'height' : 224, 'width': 224}`): Tamanho da imagem de saída após aplicar `center_crop`.

resample (`Annotated[Union[int, PILImageResampling, NoneType], None]`, *kwargs*, padrão `2`) : Filtro de reamostragem a ser usado ao redimensionar a imagem. Pode ser um dos valores da enumeração `PILImageResampling`. Tem efeito apenas se `do_resize` estiver definido como `True`.

do_rescale (`bool`, *kwargs*, *opcional*, padrão `True`) : Se deve reescalar a imagem.

rescale_factor (`float`, *kwargs*, *opcional*, padrão `0.00392156862745098`) : Fator de redimensionamento para redimensionar a imagem, caso `do_rescale` esteja definido como `True`.

do_normalize (`bool`, *kwargs*, *opcional*, padrão `True`) : Se a imagem deve ser normalizada.

image_mean (`Union[float, list[float], tuple[float, ...]]`, *kwargs*, *opcional*, padrão `[0.485, 0.456, 0.406]`) : Média da imagem a ser usada para normalização. Tem efeito apenas se `do_normalize` estiver definido como `True`.

image_std (`Union[float, list[float], tuple[float, ...]]`, *kwargs*, *opcional*, padrão `[0.229, 0.224, 0.225]`) : Desvio padrão da imagem a ser usado para normalização. Tem efeito apenas se `do_normalize` estiver definido como `True`.

do_pad (`bool`, *kwargs*, *opcional*, padrão `False`) : Se deve aplicar padding à imagem. O padding é feito até o maior tamanho do lote ou até um tamanho quadrado fixo por imagem. A estratégia exata de padding depende do modelo.

pad_size (`Annotated[int | list[int] | tuple[int, ...] | dict[str, int] | None, None]`, *kwargs*) : O tamanho em `{"height": int, "width" int}` para preencher as imagens. Deve ser maior que o tamanho de qualquer imagem fornecida para o pré-processamento. Se `pad_size` não for fornecido, as imagens serão preenchidas até a maior altura e largura do lote. Aplicado apenas quando `do_pad=True.`

do_center_crop (`bool`, *kwargs*, *opcional*, padrão `False`) : Se deve aplicar um recorte centralizado na imagem.

data_format (`Union[str, ~image_utils.ChannelDimension]`, *kwargs*, *opcional*) : Apenas `ChannelDimension.FIRST` é suportado. Adicionado para compatibilidade com processadores lentos.

input_data_format (`Union[str, ~image_utils.ChannelDimension]`, *kwargs*, *opcional*) : O formato da dimensão de canal para a imagem de entrada. Se não for definido, o formato da dimensão de canal é inferido a partir da imagem de entrada. Pode ser um dos seguintes: - `"channels_first"` ou `ChannelDimension.FIRST`: imagem no formato (num_channels, height, width). - `"channels_last"` ou `ChannelDimension.LAST`: imagem no formato (height, width, num_channels). - `"none"` ou `ChannelDimension.NONE`: imagem no formato (height, width).

device (`Annotated[Union[str, torch.device, NoneType], None]`, *kwargs*) : O dispositivo no qual os vídeos serão processados. Se não for definido, o dispositivo é inferido a partir dos vídeos de entrada.

return_tensors (`Annotated[str | ~utils.generic.TensorType | None, None]`, *kwargs*) : Retorna tensores empilhados se definido como `'pt'`, caso contrário, retorna uma lista de tensores.

disable_grouping (`bool`, *kwargs*, *opcional*) : Se deve desabilitar o agrupamento de imagens por tamanho para processá-las individualmente e não em lotes. Se for None, será definido como True se as imagens estiverem na CPU, e False caso contrário. Essa escolha é baseada em observações empíricas, conforme detalhado aqui: https://github.com/huggingface/transformers/pull/38157

image_seq_length (`int`, *kwargs*, *opcional*) : O número de tokens de imagem a serem usados para cada imagem na entrada. Adicionado para compatibilidade reversa, mas isso deve ser definido como um atributo do processador em modelos futuros.

do_reduce_labels (`bool`, *kwargs*, *opcional*, padrão `self.do_reduce_labels`) : Indica se todos os valores de rótulo dos mapas de segmentação devem ser reduzidos em 1. Geralmente usado em conjuntos de dados em que 0 é usado para o plano de fundo e o próprio plano de fundo não está incluído em todas as classes do conjunto de dados (por exemplo, ADE20k). O rótulo do plano de fundo será substituído por 255.

keypoint_heatmap_downscale_factor (`int`, *kwargs*, *opcional*, padrão é 4) : O fator de redução do tamanho do mapa de calor em relação ao tamanho de entrada do modelo.

keypoint_heatmap_sigma (`float`, *kwargs*, *opcional*, padrão 6.0) : O desvio padrão (sigma) das distribuições gaussianas 2D usadas para gerar os mapas de calor.

Constrói um processador de imagem 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'>)
```

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

**Parâmetros:**

images (`Union[PIL.Image.Image, numpy.ndarray, torch.Tensor, list[PIL.Image.Image], list[numpy.ndarray], list[torch.Tensor]]`) : Imagem a ser pré-processada. Espera uma única imagem ou um lote de imagens com valores de pixel variando de 0 a 255. Se estiver passando imagens com valores de pixel entre 0 e 1, defina `do_rescale=False`.

segmentation_maps (`ImageInput`, *opcional*) : Os mapas de segmentação a serem pré-processados.

boxes (`list[list[list[float]]]` ou `np.ndarray`, *opcional*) : Lista ou matriz de caixas delimitadoras para cada imagem. Cada caixa deve ser uma lista de 4 floats representando as coordenadas da caixa delimitadora no formato COCO (top_left_x, top_left_y, width, height). Quando fornecida, cada recorte de pessoa é submetido a uma transformação afim para o tamanho de entrada do modelo, em vez de redimensionar a imagem completa.

keypoints (`list[list[list[list[float]]]]`, *optional*) : List of keypoints for each person in each image. Expected format is COCO-style `[x, y, visibility]`. The `x` and `y` values are expected to be absolute image pixel coordinates. Format is `[images -> persons -> keypoints -> [x, y, visibility]]`. Used to generate ground-truth heatmaps and visibility weights for pose estimation fine-tuning.

do_convert_rgb (`bool`, *kwargs*, *opcional*) : Se deve converter a imagem para RGB.

do_resize (`bool`, *kwargs*, *opcional*) : Se deve redimensionar a imagem.

size (`Annotated[int | list[int] | tuple[int, ...] | dict[str, int] | None, None]`, *kwargs*) : Descreve as dimensões máximas de entrada para o modelo.

default_to_square (`bool`, *kwargs*, *opcional*) : Se deve usar uma imagem quadrada por padrão ao redimensionar, caso o tamanho seja um inteiro.

crop_size (`Annotated[int | list[int] | tuple[int, ...] | dict[str, int] | None, None]`, *kwargs*) : Tamanho da imagem de saída após aplicar `center_crop`.

resample (`Annotated[Union[int, PILImageResampling, NoneType], None]`, *kwargs*) : Filtro de redimensionamento a ser usado ao redimensionar a imagem. Pode ser um dos valores da enumeração `PILImageResampling`. Tem efeito apenas se `do_resize` estiver definido como `True`.

do_rescale (`bool`, *kwargs*, *opcional*) : Se deve reescalar a imagem.

rescale_factor (`float`, *kwargs*, *opcional*) : Fator de redimensionamento para redimensionar a imagem, caso `do_rescale` esteja definido como `True`.

do_normalize (`bool`, *kwargs*, *opcional*) : Se a imagem deve ser normalizada.

image_mean (`Union[float, list[float], tuple[float, ...]]`, *kwargs*, *opcional*) : Média da imagem a ser usada para normalização. Tem efeito apenas se `do_normalize` estiver definido como `True`.

image_std (`Union[float, list[float], tuple[float, ...]]`, *kwargs*, *opcional*) : Desvio padrão da imagem a ser usado para normalização. Tem efeito apenas se `do_normalize` estiver definido como `True`.

do_pad (`bool`, *kwargs*, *opcional*) : Se deve aplicar padding à imagem. O padding é feito até o maior tamanho do lote ou até um tamanho quadrado fixo por imagem. A estratégia exata de padding depende do modelo.

pad_size (`Annotated[int | list[int] | tuple[int, ...] | dict[str, int] | None, None]`, *kwargs*) : O tamanho em `{"height": int, "width" int}` para preencher as imagens. Deve ser maior que o tamanho de qualquer imagem fornecida para o pré-processamento. Se `pad_size` não for fornecido, as imagens serão preenchidas até a maior altura e largura do lote. Aplicado apenas quando `do_pad=True.`

do_center_crop (`bool`, *kwargs*, *opcional*) : Se deve centralizar o recorte da imagem.

data_format (`Union[str, ~image_utils.ChannelDimension]`, *kwargs*, *opcional*) : Apenas `ChannelDimension.FIRST` é suportado. Adicionado para compatibilidade com processadores lentos.

input_data_format (`Union[str, ~image_utils.ChannelDimension]`, *kwargs*, *opcional*) : O formato da dimensão de canal para a imagem de entrada. Se não for definido, o formato da dimensão de canal é inferido a partir da imagem de entrada. Pode ser um dos seguintes: - `"channels_first"` ou `ChannelDimension.FIRST`: imagem no formato (num_channels, height, width). - `"channels_last"` ou `ChannelDimension.LAST`: imagem no formato (height, width, num_channels). - `"none"` ou `ChannelDimension.NONE`: imagem no formato (height, width).

device (`Annotated[Union[str, torch.device, NoneType], None]`, *kwargs*) : O dispositivo no qual os vídeos serão processados. Se não for definido, o dispositivo é inferido a partir dos vídeos de entrada.

return_tensors (`Annotated[str | ~utils.generic.TensorType | None, None]`, *kwargs*) : Retorna tensores empilhados se definido como `'pt'`, caso contrário, retorna uma lista de tensores.

disable_grouping (`bool`, *kwargs*, *opcional*) : Se deve desabilitar o agrupamento de imagens por tamanho para processá-las individualmente e não em lotes. Se for None, será definido como True se as imagens estiverem na CPU, e False caso contrário. Essa escolha é baseada em observações empíricas, conforme detalhado aqui: https://github.com/huggingface/transformers/pull/38157

image_seq_length (`int`, *kwargs*, *opcional*) : O número de tokens de imagem a serem usados para cada imagem na entrada. Adicionado para compatibilidade reversa, mas isso deve ser definido como um atributo do processador em modelos futuros.

do_reduce_labels (`bool`, *kwargs*, *opcional*, padrão `self.do_reduce_labels`) : Indica se todos os valores de rótulo dos mapas de segmentação devem ser reduzidos em 1. Geralmente usado em conjuntos de dados em que 0 é usado para o plano de fundo e o próprio plano de fundo não está incluído em todas as classes do conjunto de dados (por exemplo, ADE20k). O rótulo do plano de fundo será substituído por 255.

keypoint_heatmap_downscale_factor (`int`, *kwargs*, *opcional*, padrão é 4) : O fator de redução do tamanho do mapa de calor em relação ao tamanho de entrada do modelo.

keypoint_heatmap_sigma (`float`, *kwargs*, *opcional*, padrão 6.0) : O desvio padrão (sigma) das distribuições gaussianas 2D usadas para gerar os mapas de calor.

**Retorna:** `~image_processing_base.BatchFeature`

- **data** (`dict`) -- Dicionário de listas/arrays/tensors retornados pelo método __call__ ('pixel_values', etc.).
- **tensor_type** (`Union[None, str, TensorType]`, *opcional*) -- Você pode fornecer um tensor_type aqui para converter as listas de inteiros em Tensors do PyTorch/Numpy na inicialização.

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

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

**Parâmetros:**

outputs (`Sapiens2ImageMattingOutput`) : Saídas brutas do modelo.

target_sizes (`torch.Tensor` ou `list[tuple[int, int]]` de comprimento `batch_size`, *opcional*) : `(height, width)` final solicitada para cada previsão. Redimensionada com interpolação bilinear. Se não definido, as previsões são retornadas na resolução de saída do modelo.

backgrounds (`ImageInput`, *opcional*) : Imagem(ns) de fundo para compor por cima. Pode ser uma única imagem (aplicada a cada item do lote) ou uma lista de imagens, uma por item do lote. Aceita imagens PIL, arrays numpy ou tensores torch de qualquer dtype; tipos inteiros (por exemplo, uint8) são escalados automaticamente para `[0, 1]`. Quando fornecida, cada dicionário de resultado ganha uma chave `"composite"` com a imagem composta como um tensor uint8 em `[0, 255]`.

**Retorna:** `list[dict]` de comprimento `batch_size`. Cada dict tem

- `"alpha"` (`torch.Tensor` de forma `(1, height, width)`): valores de alpha em `[0, 1]`.
- `"foreground"` (`torch.Tensor` de forma `(3, height, width)`): RGB pré-multiplicado em `[0, 1]`.
- `"composite"` (`torch.Tensor` de forma `(3, height, width)` ou `None`): primeiro plano composto sobre `backgrounds` como um tensor uint8 em `[0, 255]`; `None` quando `backgrounds` não é fornecido.

Converte a saída de [Sapiens2ForImageMatting](/docs/transformers/main/pt/model_doc/sapiens2#transformers.Sapiens2ForImageMatting) em máscaras alfa e mapas de primeiro plano.

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

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

**Parâmetros:**

outputs (`Sapiens2NormalEstimatorOutput`) : Saídas brutas do modelo.

source_sizes (`torch.Tensor` ou `list[tuple[int, int]]` de comprimento `batch_size`, *opcional*) : `(height, width)` original de cada imagem antes do pré-processamento. Quando fornecido, o padding adicionado durante o pré-processamento é removido e as previsões são redimensionadas de volta para o tamanho original da imagem (a menos que `target_sizes` sobrescreva o tamanho final).

target_sizes (`torch.Tensor` ou `list[tuple[int, int]]` de comprimento `batch_size`, *opcional*) : `(height, width)` final solicitado para cada previsão. Quando fornecido, é usado como o alvo de redimensionamento em vez de `source_sizes`. Redimensionado com interpolação bilinear após a normalização L2.

do_remove_padding (`bool`, *opcional*) : Se deve remover o preenchimento com zeros adicionado durante o pré-processamento antes do redimensionamento. O padrão é `True` quando `source_sizes` é fornecido, `False` caso contrário.

**Retorna:**

`list[dict[str, torch.Tensor]]` de comprimento `batch_size`. Cada dict possui uma chave `"normals"` que mapeia para um tensor de forma `(3, height, width)` com vetores unitários normalizados em L2 em `[-1, 1]` por canal (normais de superfície XYZ).

Converte a saída de [Sapiens2ForNormalEstimation](/docs/transformers/main/pt/model_doc/sapiens2#transformers.Sapiens2ForNormalEstimation) em mapas de normais de superfície normalizados em 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)
```

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

**Parâmetros:**

outputs (`Sapiens2PointmapEstimatorOutput`) : Saídas brutas do modelo.

source_sizes (`torch.Tensor` ou `list[tuple[int, int]]` de comprimento `batch_size`, *opcional*) : `(height, width)` original de cada imagem antes do pré-processamento. Quando fornecido, o padding adicionado durante o pré-processamento é removido e as previsões são redimensionadas de volta para o tamanho original da imagem (a menos que `target_sizes` sobrescreva o tamanho final).

target_sizes (`torch.Tensor` ou `list[tuple[int, int]]` de comprimento `batch_size`, *opcional*) : `(height, width)` final solicitada para cada previsão. Substitui `source_sizes` como o alvo de redimensionamento.

do_remove_padding (`bool`, *opcional*) : Se deve remover o preenchimento com zeros adicionado durante o pré-processamento antes do redimensionamento. O padrão é `True` quando `source_sizes` é fornecido, `False` caso contrário.

**Retorna:**

`list[dict[str, torch.Tensor]]` de comprimento `batch_size`. Cada dict possui uma chave `"pointmap"` que mapeia para um tensor de forma `(3, height, width)` com coordenadas 3D XYZ por pixel no espaço de câmera canônico, opcionalmente divididas por `outputs.scales` para converter em coordenadas métricas.

Converte a saída de [Sapiens2ForPointmapEstimation](/docs/transformers/main/pt/model_doc/sapiens2#transformers.Sapiens2ForPointmapEstimation) em tensores de pointmap no espaço da imagem.

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

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

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

**Parâmetros:**

outputs (`Sapiens2PoseEstimatorOutput`) : Saídas brutas do modelo. `outputs.heatmaps` deve ter a forma `(N_total, num_keypoints, heatmap_height, heatmap_width)`, onde `N_total = sum(len(b) for b in boxes)`.

boxes (`list[list[list[float]]]` ou `np.ndarray`) : Lista ou matriz de caixas delimitadoras para cada imagem em coordenadas de pixels absolutas. Cada caixa deve ser uma lista de 4 floats representando as coordenadas da caixa delimitadora no formato COCO (top_left_x, top_left_y, width, height). Deve corresponder ao argumento `boxes` passado para `preprocess`.

outputs_flipped (`Sapiens2PoseEstimatorOutput`, *opcional*) : Saídas obtidas ao executar o modelo em entradas horizontalmente invertidas. Quando fornecidas, os mapas de calor são média com `outputs` antes da extração dos pontos-chave para melhorar a precisão: `avg_heatmaps = (outputs.heatmaps + outputs_flipped.heatmaps) / 2`.

kernel_size (`int`, *opcional*, padrão 11) : Tamanho do kernel para o desfoque gaussiano usado no refinamento de UDP Dark Pose.

threshold (`float`, *opcional*) : Limiar de pontuação. Pontos-chave com pontuações iguais ou inferiores a esse valor são filtrados dos dicionários de resultado.

source_sizes (`torch.Tensor` or `list[tuple[int, int]]` of length `batch_size`, *optional*) : Original `(height, width)` of each image in pixels. Required when `target_sizes` is provided, as the source coordinate space for scaling keypoints and bounding boxes.

target_sizes (`torch.Tensor` ou `list[tuple[int, int]]` de comprimento `batch_size`, *opcional*) : Espaço de coordenadas de saída `(height, width)` desejado para cada imagem. Quando fornecido junto com `source_sizes`, as coordenadas dos pontos-chave e as caixas delimitadoras são escaladas do espaço de origem para o espaço de destino.

**Retorna:** `list[list[dict]]`

A lista externa é sobre imagens, a lista interna é sobre pessoas. Cada dict contém:
- `keypoints` (`torch.Tensor` de forma `(num_keypoints, 2)`): coordenadas x/y absolutas no espaço da imagem de origem, ou no espaço de destino se `target_sizes` for fornecido.
- `scores` (`torch.Tensor` de forma `(num_keypoints,)`): confiança por ponto-chave.
- `labels` (`torch.LongTensor` de forma `(num_keypoints,)`): índices dos pontos-chave.
- `bbox` (`torch.Tensor` de forma `(4,)`): caixa delimitadora no formato absoluto (x_min, y_min, x_max, y_max), no mesmo espaço de coordenadas que `keypoints`.

Converte a saída de [Sapiens2ForPoseEstimation](/docs/transformers/main/pt/model_doc/sapiens2#transformers.Sapiens2ForPoseEstimation) em previsões de pontos-chave no espaço da imagem.

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

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

**Parâmetros:**

outputs ([Sapiens2ForSemanticSegmentation](/docs/transformers/main/pt/model_doc/sapiens2#transformers.Sapiens2ForSemanticSegmentation)) : Saídas brutas do modelo.

target_sizes (`list[Tuple]` de comprimento `batch_size`, *opcional*) : Lista de tuplas correspondente ao tamanho final solicitado (altura, largura) de cada previsão. Se não definido, as previsões não serão redimensionadas.

return_segmentation_scores (`bool`, *opcional*, padrão `False`) : Se deve retornar as pontuações de segmentação junto com o mapa de segmentação. Quando `True`, cada elemento da lista retornada é um `SemanticSegmentationPostProcessorOutput` com os campos `segmentation` (IDs de classe, forma `(height, width)`) e `segmentation_scores` (forma `(num_classes, height, width)`).

**Retorna:** `list[torch.Tensor]` ou `list[SemanticSegmentationPostProcessorOutput]`

Quando `return_segmentation_scores=False` (padrão), uma lista de comprimento `batch_size` em que cada item é um mapa de segmentação de forma `(height, width)` com IDs de classe. Quando `return_segmentation_scores=True`, uma lista de `SemanticSegmentationPostProcessorOutput` com os campos `segmentation` (IDs de classe, forma `(height, width)`) e `segmentation_scores` (forma `(num_classes, height, width)`). Em ambos os casos, `(height, width)` corresponde ao tamanho alvo (se `target_sizes` for especificado).

Converte a saída de [Sapiens2ForSemanticSegmentation](/docs/transformers/main/pt/model_doc/sapiens2#transformers.Sapiens2ForSemanticSegmentation) em mapas de segmentação semântica.

## Sapiens2Model[[transformers.Sapiens2Model]]

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

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

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

**Parâmetros:**

config ([Sapiens2Config](/docs/transformers/main/pt/model_doc/sapiens2#transformers.Sapiens2Config)) : Classe de configuração do modelo com todos os parâmetros do modelo. A inicialização com um arquivo de configuração não carrega os pesos associados ao modelo, apenas a configuração. Consulte o método [from_pretrained()](/docs/transformers/main/pt/main_classes/model#transformers.PreTrainedModel.from_pretrained) para carregar os pesos do modelo.

O modelo Sapiens2 puro, que produz estados ocultos brutos sem nenhum cabeçalho específico no topo.

Este modelo herda de [PreTrainedModel](/docs/transformers/main/pt/main_classes/model#transformers.PreTrainedModel). Consulte a documentação da classe pai para os métodos genéricos que a biblioteca implementa para todos os seus modelos (como download ou salvamento, redimensionamento dos embeddings de entrada, poda de cabeças, etc.).

Este modelo também é uma subclasse de [torch.nn.Module](https://pytorch.org/docs/stable/nn.html#torch.nn.Module) do PyTorch. Use-o como um Módulo PyTorch regular e consulte a documentação do PyTorch para todos os assuntos relacionados ao uso e comportamento gerais.

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

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

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

**Parâmetros:**

pixel_values (`torch.Tensor` de forma `(batch_size, num_channels, image_size, image_size)`) : Os tensores correspondentes às imagens de entrada. Os valores de pixels podem ser obtidos usando [Sapiens2ImageProcessor](/docs/transformers/main/pt/model_doc/sapiens2#transformers.Sapiens2ImageProcessor). Veja [Sapiens2ImageProcessor.__call__()](/docs/transformers/main/pt/model_doc/molmo2#transformers.Molmo2ImageProcessor.__call__) para detalhes (`processor_class` usa [Sapiens2ImageProcessor](/docs/transformers/main/pt/model_doc/sapiens2#transformers.Sapiens2ImageProcessor) para processar imagens).

bool_masked_pos (`torch.BoolTensor` de forma `(batch_size, sequence_length)`, *opcional*) : Posições mascaradas booleanas. Indica quais patches estão mascarados (1) e quais não estão (0). Relevante apenas para pré-treinamento.

**Retorna:** [BaseModelOutputWithPooling](/docs/transformers/main/pt/main_classes/output#transformers.modeling_outputs.BaseModelOutputWithPooling) ou `tuple(torch.Tensor)`

Um [BaseModelOutputWithPooling](/docs/transformers/main/pt/main_classes/output#transformers.modeling_outputs.BaseModelOutputWithPooling) ou uma tupla de `torch.Tensor` (se `return_dict=False` for passado ou quando `config.return_dict=False`) contendo vários elementos dependendo da configuração ([Sapiens2Config](/docs/transformers/main/pt/model_doc/sapiens2#transformers.Sapiens2Config)) e das entradas.

O método forward do [Sapiens2Model](/docs/transformers/main/pt/model_doc/sapiens2#transformers.Sapiens2Model) sobrescreve o método especial `__call__`.

Embora a receita para a passagem direta precise ser definida dentro desta função, deve-se chamar a instância de `Module` em seguida, em vez desta, pois a primeira cuida da execução das etapas de pré e pós-processamento, enquanto a segunda as ignora silenciosamente.

- **last_hidden_state** (`torch.Tensor` de forma `(batch_size, sequence_length, hidden_size)`) -- Sequência de estados ocultos na saída da última camada do modelo.
- **pooler_output** (`torch.Tensor` de forma `(batch_size, hidden_size)`) -- Estado oculto da última camada do primeiro token da sequência (token de classificação) após processamento adicional pelas camadas usadas para a tarefa de pré-treinamento auxiliar. Por exemplo, para modelos da família BERT, isso retorna o token de classificação após o processamento por uma camada linear e uma função de ativação tanh. Os pesos da camada linear são treinados a partir do objetivo de previsão da próxima frase (classificação) durante o pré-treinamento.
- **hidden_states** (`tuple(torch.Tensor)`, *opcional*, retornado quando `output_hidden_states=True` é passado ou quando `config.output_hidden_states=True`) -- Tupla de `torch.Tensor` (um para a saída dos embeddings, se o modelo tiver uma camada de embedding, + um para a saída de cada camada) com a forma `(batch_size, sequence_length, hidden_size)`.

  Estados ocultos do modelo na saída de cada camada, além das saídas opcionais do embedding inicial.
- **attentions** (`tuple(torch.Tensor)`, *opcional*, retornado quando `output_attentions=True` é passado ou quando `config.output_attentions=True`) -- Tupla de `torch.Tensor` (um para cada camada) com a forma `(batch_size, num_heads, sequence_length, sequence_length)`.

  Pesos de atenção após o softmax de atenção, usados para calcular a média ponderada nas cabeças de autoatenção.

Exemplo:

```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)
```

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

**Parâmetros:**

config ([Sapiens2Config](/docs/transformers/main/pt/model_doc/sapiens2#transformers.Sapiens2Config)) : Classe de configuração do modelo com todos os parâmetros do modelo. A inicialização com um arquivo de configuração não carrega os pesos associados ao modelo, apenas a configuração. Consulte o método [from_pretrained()](/docs/transformers/main/pt/main_classes/model#transformers.PreTrainedModel.from_pretrained) para carregar os pesos do modelo.

O backbone Sapiens2.

Este modelo herda de [PreTrainedModel](/docs/transformers/main/pt/main_classes/model#transformers.PreTrainedModel). Consulte a documentação da classe pai para os métodos genéricos que a biblioteca implementa para todos os seus modelos (como download ou salvamento, redimensionamento dos embeddings de entrada, poda de cabeças, etc.).

Este modelo também é uma subclasse de [torch.nn.Module](https://pytorch.org/docs/stable/nn.html#torch.nn.Module) do PyTorch. Use-o como um Módulo PyTorch regular e consulte a documentação do PyTorch para todos os assuntos relacionados ao uso e comportamento gerais.

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

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

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

**Parâmetros:**

pixel_values (`torch.Tensor` de forma `(batch_size, num_channels, image_size, image_size)`) : Os tensores correspondentes às imagens de entrada. Os valores de pixels podem ser obtidos usando [Sapiens2ImageProcessor](/docs/transformers/main/pt/model_doc/sapiens2#transformers.Sapiens2ImageProcessor). Veja [Sapiens2ImageProcessor.__call__()](/docs/transformers/main/pt/model_doc/molmo2#transformers.Molmo2ImageProcessor.__call__) para detalhes (`processor_class` usa [Sapiens2ImageProcessor](/docs/transformers/main/pt/model_doc/sapiens2#transformers.Sapiens2ImageProcessor) para processar imagens).

**Retorna:** `Sapiens2BackboneOutput` ou `tuple(torch.Tensor)`

Um `Sapiens2BackboneOutput` ou uma tupla de `torch.Tensor` (se `return_dict=False` for passado ou quando `config.return_dict=False`) contendo vários elementos, dependendo da configuração ([Sapiens2Config](/docs/transformers/main/pt/model_doc/sapiens2#transformers.Sapiens2Config)) e das entradas.

O método forward de [Sapiens2Backbone](/docs/transformers/main/pt/model_doc/sapiens2#transformers.Sapiens2Backbone) substitui o método especial `__call__`.

Embora a receita para a passagem direta precise ser definida dentro desta função, deve-se chamar a instância de `Module` em seguida, em vez desta, pois a primeira cuida da execução das etapas de pré e pós-processamento, enquanto a segunda as ignora silenciosamente.

- **feature_maps** (`tuple(torch.Tensor)` de forma `(batch_size, num_channels, height, width)`) -- Mapas de características dos estágios.
- **hidden_states** (`tuple(torch.Tensor)`, *opcional*, retornado quando `output_hidden_states=True` é passado ou quando `config.output_hidden_states=True`) -- Tupla de `torch.Tensor` (um para a saída dos embeddings + um para a saída de cada camada) de forma `(batch_size, sequence_length, hidden_size)` ou `(batch_size, num_channels, height, width)`, dependendo do backbone.

  Estados ocultos do modelo na saída de cada estágio, além das saídas do embedding inicial.
- **attentions** (`tuple(torch.Tensor)`, *opcional*, retornado quando `output_attentions=True` é passado ou quando `config.output_attentions=True`) -- Tupla de `torch.Tensor` (um para cada camada) com a forma `(batch_size, num_heads, sequence_length, sequence_length)`. Aplicável apenas se o backbone usar atenção.

  Pesos de atenção após o softmax de atenção, usados para calcular a média ponderada nas cabeças de autoatenção.
- **cls_tokens** (`tuple(torch.Tensor)`, *opcional*) -- Token CLS de cada estágio de recurso selecionado, cada um com forma `(batch_size, hidden_size)`. Presente apenas quando `config.return_class_token=True`.

Exemplo:

```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)
```

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

**Parâmetros:**

config ([Sapiens2Config](/docs/transformers/main/pt/model_doc/sapiens2#transformers.Sapiens2Config)) : Classe de configuração do modelo com todos os parâmetros do modelo. A inicialização com um arquivo de configuração não carrega os pesos associados ao modelo, apenas a configuração. Consulte o método [from_pretrained()](/docs/transformers/main/pt/main_classes/model#transformers.PreTrainedModel.from_pretrained) para carregar os pesos do modelo.

O modelo Sapiens2 com uma cabeça de matting no topo (um decodificador baseado em PixelShuffle que prevê um primeiro plano RGB pré-multiplicado e uma máscara alfa).

Este modelo herda de [PreTrainedModel](/docs/transformers/main/pt/main_classes/model#transformers.PreTrainedModel). Consulte a documentação da classe pai para os métodos genéricos que a biblioteca implementa para todos os seus modelos (como download ou salvamento, redimensionamento dos embeddings de entrada, poda de cabeças, etc.).

Este modelo também é uma subclasse de [torch.nn.Module](https://pytorch.org/docs/stable/nn.html#torch.nn.Module) do PyTorch. Use-o como um Módulo PyTorch regular e consulte a documentação do PyTorch para todos os assuntos relacionados ao uso e comportamento gerais.

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

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

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

**Parâmetros:**

pixel_values (`torch.Tensor` de forma `(batch_size, num_channels, image_size, image_size)`) : Os tensores correspondentes às imagens de entrada. Os valores de pixels podem ser obtidos usando [Sapiens2ImageProcessor](/docs/transformers/main/pt/model_doc/sapiens2#transformers.Sapiens2ImageProcessor). Veja [Sapiens2ImageProcessor.__call__()](/docs/transformers/main/pt/model_doc/molmo2#transformers.Molmo2ImageProcessor.__call__) para detalhes (`processor_class` usa [Sapiens2ImageProcessor](/docs/transformers/main/pt/model_doc/sapiens2#transformers.Sapiens2ImageProcessor) para processar imagens).

labels (`torch.Tensor` de forma `(batch_size, 4, height, width)`, *opcional*) : Alvos de matting reais para o cálculo da perda.

**Retorna:** `Sapiens2ImageMattingOutput` ou `tuple(torch.Tensor)`

Um `Sapiens2ImageMattingOutput` ou uma tupla de `torch.Tensor` (se `return_dict=False` for passado ou quando `config.return_dict=False`) contendo vários elementos, dependendo da configuração ([Sapiens2Config](/docs/transformers/main/pt/model_doc/sapiens2#transformers.Sapiens2Config)) e das entradas.

O método forward de [Sapiens2ForImageMatting](/docs/transformers/main/pt/model_doc/sapiens2#transformers.Sapiens2ForImageMatting) substitui o método especial `__call__`.

Embora a receita para a passagem direta precise ser definida dentro desta função, deve-se chamar a instância de `Module` em seguida, em vez desta, pois a primeira cuida da execução das etapas de pré e pós-processamento, enquanto a segunda as ignora silenciosamente.

- **loss** (`torch.Tensor` de forma `(1,)`, *opcional*, retornado quando `labels` é fornecido) -- Perda.
- **alphas** (`torch.Tensor` de forma `(batch_size, 1, height, width)`) -- Valores de alpha estimados.
- **hidden_states** (`tuple(torch.Tensor)`, *opcional*, retornado quando `output_hidden_states=True` é passado ou quando `config.output_hidden_states=True`) -- Tupla de `torch.Tensor` (uma para a saída dos embeddings, se o modelo tiver uma camada de embedding, + uma para a saída de cada estágio) de forma `(batch_size, sequence_length, hidden_size)`. Hidden-states (também chamados de feature maps) do modelo na saída de cada estágio.
- **attentions** (`tuple[torch.Tensor]`, *opcional*, retornado quando `output_attentions=True` é passado ou quando `config.output_attentions=True`) -- Tupla de `torch.Tensor` (um para cada camada) com a forma `(batch_size, num_heads, sequence_length, sequence_length)`.

  Pesos de atenção após o softmax de atenção, usados para calcular a média ponderada nas cabeças de autoatenção.
- **primeiros planos** (`torch.Tensor` de forma `(batch_size, 3, height, width)`) -- Previsões de primeiro plano RGB pré-multiplicadas em `[0, 1]` (ativadas por sigmoid).

Exemplo:

```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)
```

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

**Parâmetros:**

config ([Sapiens2Config](/docs/transformers/main/pt/model_doc/sapiens2#transformers.Sapiens2Config)) : Classe de configuração do modelo com todos os parâmetros do modelo. A inicialização com um arquivo de configuração não carrega os pesos associados ao modelo, apenas a configuração. Consulte o método [from_pretrained()](/docs/transformers/main/pt/main_classes/model#transformers.PreTrainedModel.from_pretrained) para carregar os pesos do modelo.

O modelo Sapiens2 com uma cabeça de estimativa de normais no topo (um decodificador baseado em PixelShuffle que prevê mapas de normais de superfície).

Este modelo herda de [PreTrainedModel](/docs/transformers/main/pt/main_classes/model#transformers.PreTrainedModel). Consulte a documentação da classe pai para os métodos genéricos que a biblioteca implementa para todos os seus modelos (como download ou salvamento, redimensionamento dos embeddings de entrada, poda de cabeças, etc.).

Este modelo também é uma subclasse de [torch.nn.Module](https://pytorch.org/docs/stable/nn.html#torch.nn.Module) do PyTorch. Use-o como um Módulo PyTorch regular e consulte a documentação do PyTorch para todos os assuntos relacionados ao uso e comportamento gerais.

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

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

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

**Parâmetros:**

pixel_values (`torch.Tensor` de forma `(batch_size, num_channels, image_size, image_size)`) : Os tensores correspondentes às imagens de entrada. Os valores de pixels podem ser obtidos usando [Sapiens2ImageProcessor](/docs/transformers/main/pt/model_doc/sapiens2#transformers.Sapiens2ImageProcessor). Veja [Sapiens2ImageProcessor.__call__()](/docs/transformers/main/pt/model_doc/molmo2#transformers.Molmo2ImageProcessor.__call__) para detalhes (`processor_class` usa [Sapiens2ImageProcessor](/docs/transformers/main/pt/model_doc/sapiens2#transformers.Sapiens2ImageProcessor) para processar imagens).

labels (`torch.Tensor` de forma `(batch_size, num_labels, height, width)`, *opcional*) : Mapas de normais de superfície verdadeiros para o cálculo da perda.

**Retorna:** `Sapiens2NormalEstimatorOutput` ou `tuple(torch.Tensor)`

Um `Sapiens2NormalEstimatorOutput` ou uma tupla de `torch.Tensor` (se `return_dict=False` for passado ou quando `config.return_dict=False`) contendo vários elementos, dependendo da configuração ([Sapiens2Config](/docs/transformers/main/pt/model_doc/sapiens2#transformers.Sapiens2Config)) e das entradas.

O método forward de [Sapiens2ForNormalEstimation](/docs/transformers/main/pt/model_doc/sapiens2#transformers.Sapiens2ForNormalEstimation) substitui o método especial `__call__`.

Embora a receita para a passagem direta precise ser definida dentro desta função, deve-se chamar a instância de `Module` em seguida, em vez desta, pois a primeira cuida da execução das etapas de pré e pós-processamento, enquanto a segunda as ignora silenciosamente.

- **loss** (`torch.Tensor` de forma `(1,)`, *opcional*, retornado quando `labels` é fornecido) -- Perda de estimativa normal.
- **normals** (`torch.Tensor` de forma `(batch_size, num_labels, height, width)`) -- Previsões brutas do mapa de normais produzidas pelo modelo (não normalizadas).
- **hidden_states** (`tuple(torch.Tensor)`, *opcional*, retornado quando `output_hidden_states=True` é passado ou quando `config.output_hidden_states=True`) -- Tupla de `torch.Tensor` (um para a saída dos embeddings + um para a saída de cada estágio) com forma `(batch_size, sequence_length, hidden_size)`. Hidden-states do modelo na saída de cada camada, além das saídas dos embeddings iniciais.
- **attentions** (`tuple(torch.Tensor)`, *opcional*, retornado quando `output_attentions=True` é passado ou quando `config.output_attentions=True`) -- Tupla de `torch.Tensor` (um por camada) com a forma `(batch_size, num_heads, sequence_length, sequence_length)`. Pesos de atenção após o softmax de atenção.

Exemplo:

```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)
```

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

**Parâmetros:**

config ([Sapiens2Config](/docs/transformers/main/pt/model_doc/sapiens2#transformers.Sapiens2Config)) : Classe de configuração do modelo com todos os parâmetros do modelo. A inicialização com um arquivo de configuração não carrega os pesos associados ao modelo, apenas a configuração. Consulte o método [from_pretrained()](/docs/transformers/main/pt/main_classes/model#transformers.PreTrainedModel.from_pretrained) para carregar os pesos do modelo.

O modelo Sapiens2 com uma cabeça de pointmap no topo (um decodificador baseado em PixelShuffle que prevê coordenadas 3D XYZ por pixel, além de um ramo opcional de escala para normalização da distância focal).

Este modelo herda de [PreTrainedModel](/docs/transformers/main/pt/main_classes/model#transformers.PreTrainedModel). Consulte a documentação da classe pai para os métodos genéricos que a biblioteca implementa para todos os seus modelos (como download ou salvamento, redimensionamento dos embeddings de entrada, poda de cabeças, etc.).

Este modelo também é uma subclasse de [torch.nn.Module](https://pytorch.org/docs/stable/nn.html#torch.nn.Module) do PyTorch. Use-o como um Módulo PyTorch regular e consulte a documentação do PyTorch para todos os assuntos relacionados ao uso e comportamento gerais.

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

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

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

**Parâmetros:**

pixel_values (`torch.Tensor` de forma `(batch_size, num_channels, image_size, image_size)`) : Os tensores correspondentes às imagens de entrada. Os valores de pixels podem ser obtidos usando [Sapiens2ImageProcessor](/docs/transformers/main/pt/model_doc/sapiens2#transformers.Sapiens2ImageProcessor). Veja [Sapiens2ImageProcessor.__call__()](/docs/transformers/main/pt/model_doc/molmo2#transformers.Molmo2ImageProcessor.__call__) para detalhes (`processor_class` usa [Sapiens2ImageProcessor](/docs/transformers/main/pt/model_doc/sapiens2#transformers.Sapiens2ImageProcessor) para processar imagens).

labels (`torch.Tensor` de forma `(batch_size, 3, height, width)`, *opcional*) : Pointmap de referência para o cálculo da perda.

**Retorna:** `Sapiens2PointmapEstimatorOutput` ou `tuple(torch.Tensor)`

Um `Sapiens2PointmapEstimatorOutput` ou uma tupla de `torch.Tensor` (se `return_dict=False` for passado ou quando `config.return_dict=False`) contendo vários elementos, dependendo da configuração ([Sapiens2Config](/docs/transformers/main/pt/model_doc/sapiens2#transformers.Sapiens2Config)) e das entradas.

O método forward de [Sapiens2ForPointmapEstimation](/docs/transformers/main/pt/model_doc/sapiens2#transformers.Sapiens2ForPointmapEstimation) substitui o método especial `__call__`.

Embora a receita para a passagem direta precise ser definida dentro desta função, deve-se chamar a instância de `Module` em seguida, em vez desta, pois a primeira cuida da execução das etapas de pré e pós-processamento, enquanto a segunda as ignora silenciosamente.

- **loss** (`torch.Tensor` de forma `(1,)`, *opcional*, retornado quando `labels` é fornecido) -- Perda de estimativa de Pointmap.
- **pointmaps** (`torch.Tensor` de forma `(batch_size, 3, height, width)`) -- Previsões de coordenadas 3D XYZ por pixel no espaço da câmera canônica.
- **scales** (`torch.Tensor` de forma `(batch_size, 1)`, *opcional*) -- Razão entre a distância focal canônica e a distância focal real. `None` quando nenhum ramo de escala é configurado.
- **hidden_states** (`tuple(torch.Tensor)`, *opcional*, retornado quando `output_hidden_states=True` é passado ou quando `config.output_hidden_states=True`) -- Tupla de `torch.Tensor` (um para a saída dos embeddings + um para a saída de cada estágio) com forma `(batch_size, sequence_length, hidden_size)`. Hidden-states do modelo na saída de cada camada, além das saídas dos embeddings iniciais.
- **attentions** (`tuple(torch.Tensor)`, *opcional*, retornado quando `output_attentions=True` é passado ou quando `config.output_attentions=True`) -- Tupla de `torch.Tensor` (um por camada) com a forma `(batch_size, num_heads, sequence_length, sequence_length)`. Pesos de atenção após o softmax de atenção.

Exemplo:

```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)
```

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

**Parâmetros:**

config ([Sapiens2Config](/docs/transformers/main/pt/model_doc/sapiens2#transformers.Sapiens2Config)) : Classe de configuração do modelo com todos os parâmetros do modelo. A inicialização com um arquivo de configuração não carrega os pesos associados ao modelo, apenas a configuração. Consulte o método [from_pretrained()](/docs/transformers/main/pt/main_classes/model#transformers.PreTrainedModel.from_pretrained) para carregar os pesos do modelo.

O modelo Sapiens2 com uma cabeça de estimativa de pose no topo (um conjunto de preditores de mapa de calor sobre a saída dos estados ocultos).

Este modelo herda de [PreTrainedModel](/docs/transformers/main/pt/main_classes/model#transformers.PreTrainedModel). Consulte a documentação da classe pai para os métodos genéricos que a biblioteca implementa para todos os seus modelos (como download ou salvamento, redimensionamento dos embeddings de entrada, poda de cabeças, etc.).

Este modelo também é uma subclasse de [torch.nn.Module](https://pytorch.org/docs/stable/nn.html#torch.nn.Module) do PyTorch. Use-o como um Módulo PyTorch regular e consulte a documentação do PyTorch para todos os assuntos relacionados ao uso e comportamento gerais.

#### 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'>)
```

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

**Parâmetros:**

pixel_values (`torch.Tensor` de forma `(batch_size, num_channels, image_size, image_size)`) : Os tensores correspondentes às imagens de entrada. Os valores de pixels podem ser obtidos usando [Sapiens2ImageProcessor](/docs/transformers/main/pt/model_doc/sapiens2#transformers.Sapiens2ImageProcessor). Veja [Sapiens2ImageProcessor.__call__()](/docs/transformers/main/pt/model_doc/molmo2#transformers.Molmo2ImageProcessor.__call__) para detalhes (`processor_class` usa [Sapiens2ImageProcessor](/docs/transformers/main/pt/model_doc/sapiens2#transformers.Sapiens2ImageProcessor) para processar imagens).

flip_pairs (`torch.Tensor` de forma `(num_pairs, 2)`, *opcional*) : Pares de pontos-chave que são espelhados (por exemplo, orelha esquerda -- orelha direita), usados para aumento de dados por inversão no momento do teste. Quando fornecido, o modelo assume que `pixel_values` contém imagens invertidas horizontalmente e chama `flip_back` nos mapas de calor de saída para restaurar a orientação original.

labels (`torch.Tensor` de forma `(batch_size, num_keypoints, height, width)`, *opcional*) : Ground truth do heatmap para o cálculo da perda.

label_weights (`torch.Tensor` de forma `(batch_size, num_labels, 1, 1)` ou `(batch_size, num_labels, height, width)`, *opcional*) : Pesos de visibilidade para cada ponto-chave. Deve ser broadcastável para a forma de `labels`.

**Retorna:** `Sapiens2PoseEstimatorOutput` ou `tuple(torch.Tensor)`

Um `Sapiens2PoseEstimatorOutput` ou uma tupla de `torch.Tensor` (se `return_dict=False` for passado ou quando `config.return_dict=False`) contendo vários elementos, dependendo da configuração ([Sapiens2Config](/docs/transformers/main/pt/model_doc/sapiens2#transformers.Sapiens2Config)) e das entradas.

O método forward de [Sapiens2ForPoseEstimation](/docs/transformers/main/pt/model_doc/sapiens2#transformers.Sapiens2ForPoseEstimation) substitui o método especial `__call__`.

Embora a receita para a passagem direta precise ser definida dentro desta função, deve-se chamar a instância de `Module` em seguida, em vez desta, pois a primeira cuida da execução das etapas de pré e pós-processamento, enquanto a segunda as ignora silenciosamente.

- **loss** (`torch.Tensor` de forma `(1,)`, *opcional*, retornado quando `labels` é fornecido) -- Perda de estimativa de pose.
- **mapas de calor** (`torch.Tensor` de forma `(batch_size, num_keypoints, height, width)`) -- Mapas de calor previstos pelo modelo.
- **hidden_states** (`tuple(torch.Tensor)`, *opcional*, retornado quando `output_hidden_states=True` é passado ou quando `config.output_hidden_states=True`) -- Tupla de `torch.Tensor` (uma para a saída dos embeddings, se o modelo tiver uma camada de embedding, + uma para a saída de cada estágio) de forma `(batch_size, sequence_length, hidden_size)`. Hidden-states (também chamados de feature maps) do modelo na saída de cada estágio.
- **attentions** (`tuple[torch.Tensor, ...]`, *opcional*, retornado quando `output_attentions=True` é passado ou quando `config.output_attentions=True`) -- Tupla de `torch.Tensor` (uma para cada camada) de forma `(batch_size, num_heads, sequence_length, sequence_length)`.

  Pesos de atenção após o softmax de atenção, usados para calcular a média ponderada nas cabeças de autoatenção.

Exemplo:

```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)
```

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

**Parâmetros:**

config ([Sapiens2Config](/docs/transformers/main/pt/model_doc/sapiens2#transformers.Sapiens2Config)) : Classe de configuração do modelo com todos os parâmetros do modelo. A inicialização com um arquivo de configuração não carrega os pesos associados ao modelo, apenas a configuração. Consulte o método [from_pretrained()](/docs/transformers/main/pt/main_classes/model#transformers.PreTrainedModel.from_pretrained) para carregar os pesos do modelo.

O modelo Sapiens2 com uma cabeça de segmentação semântica no topo, por exemplo, para ADE20K, CityScapes.

Este modelo herda de [PreTrainedModel](/docs/transformers/main/pt/main_classes/model#transformers.PreTrainedModel). Consulte a documentação da classe pai para os métodos genéricos que a biblioteca implementa para todos os seus modelos (como download ou salvamento, redimensionamento dos embeddings de entrada, poda de cabeças, etc.).

Este modelo também é uma subclasse de [torch.nn.Module](https://pytorch.org/docs/stable/nn.html#torch.nn.Module) do PyTorch. Use-o como um Módulo PyTorch regular e consulte a documentação do PyTorch para todos os assuntos relacionados ao uso e comportamento gerais.

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

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

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

**Parâmetros:**

pixel_values (`torch.Tensor` de forma `(batch_size, num_channels, image_size, image_size)`) : Os tensores correspondentes às imagens de entrada. Os valores de pixels podem ser obtidos usando [Sapiens2ImageProcessor](/docs/transformers/main/pt/model_doc/sapiens2#transformers.Sapiens2ImageProcessor). Veja [Sapiens2ImageProcessor.__call__()](/docs/transformers/main/pt/model_doc/molmo2#transformers.Molmo2ImageProcessor.__call__) para detalhes (`processor_class` usa [Sapiens2ImageProcessor](/docs/transformers/main/pt/model_doc/sapiens2#transformers.Sapiens2ImageProcessor) para processar imagens).

labels (`torch.LongTensor` de forma `(batch_size, height, width)`, *opcional*) : Mapas de segmentação semântica de verdade para o cálculo da perda. Os índices devem estar em `[0, ..., config.num_labels - 1]`. Se `config.num_labels > 1`, uma perda de classificação é calculada (Cross-Entropy).

**Retorna:** [SemanticSegmenterOutput](/docs/transformers/main/pt/main_classes/output#transformers.modeling_outputs.SemanticSegmenterOutput) ou `tuple(torch.Tensor)`

Um [SemanticSegmenterOutput](/docs/transformers/main/pt/main_classes/output#transformers.modeling_outputs.SemanticSegmenterOutput) ou uma tupla de `torch.Tensor` (se `return_dict=False` for passado ou quando `config.return_dict=False`) contendo vários elementos dependendo da configuração ([Sapiens2Config](/docs/transformers/main/pt/model_doc/sapiens2#transformers.Sapiens2Config)) e das entradas.

O método forward de [Sapiens2ForSemanticSegmentation](/docs/transformers/main/pt/model_doc/sapiens2#transformers.Sapiens2ForSemanticSegmentation) substitui o método especial `__call__`.

Embora a receita para a passagem direta precise ser definida dentro desta função, deve-se chamar a instância de `Module` em seguida, em vez desta, pois a primeira cuida da execução das etapas de pré e pós-processamento, enquanto a segunda as ignora silenciosamente.

- **loss** (`torch.Tensor` de forma `(1,)`, *opcional*, retornado quando `labels` é fornecido) -- Perda de classificação (ou de regressão se config.num_labels==1).
- **logits** (`torch.Tensor` de forma `(batch_size, config.num_labels, logits_height, logits_width)`) -- Pontuações de classificação para cada pixel.

  

  Os logits retornados não necessariamente têm o mesmo tamanho que os `pixel_values` passados como entradas. Isso é para evitar realizar duas interpolações e perder alguma qualidade quando um usuário precisa redimensionar os logits para o tamanho da imagem original como pós-processamento. Você deve sempre verificar a forma dos seus logits e redimensioná-los conforme necessário.

  
- **hidden_states** (`tuple(torch.Tensor)`, *opcional*, retornado quando `output_hidden_states=True` é passado ou quando `config.output_hidden_states=True`) -- Tupla de `torch.Tensor` (um para a saída dos embeddings, se o modelo tiver uma camada de embedding, + um para a saída de cada camada) de forma `(batch_size, patch_size, hidden_size)`.

  Estados ocultos do modelo na saída de cada camada, além das saídas opcionais do embedding inicial.
- **attentions** (`tuple(torch.Tensor)`, *opcional*, retornado quando `output_attentions=True` é passado ou quando `config.output_attentions=True`) -- Tupla de `torch.Tensor` (uma para cada camada) de forma `(batch_size, num_heads, patch_size, sequence_length)`.

  Pesos de atenção após o softmax de atenção, usados para calcular a média ponderada nas cabeças de autoatenção.

Exemplo:

```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])
```