# SAM3 Tracker

    
        
        
    

## Visão geral

SAM3 (Segment Anything Model 3) foi introduzido em [SAM 3: Segment Anything with Concepts](https://ai.meta.com/research/publications/sam-3-segment-anything-with-concepts/).

O Sam3Tracker executa **Segmentação Visual Promptável (PVS)** em imagens. A PVS utiliza prompts visuais interativos (pontos, caixas, máscaras) ou entradas de texto para segmentar uma **instância de objeto específica** por prompt. Essa é a tarefa em que o SAM 1 e o SAM 2 se concentraram, e o SAM 3 a aprimora.

Sam3Tracker é uma versão atualizada do SAM2 (Segment Anything Model 2) que mantém a mesma API, ao mesmo tempo em que oferece desempenho e capacidades aprimorados.

O resumo do artigo é o seguinte:

*Apresentamos o Segment Anything Model (SAM) 3, um modelo unificado que detecta, segmenta e rastreia objetos em imagens e vídeos com base em prompts de conceito, que definimos como frases nominais curtas (por exemplo, "yellow school bus"), exemplares de imagem ou uma combinação de ambos. A Segmentação de Conceitos Promptável (PCS) recebe esses prompts e retorna máscaras de segmentação e identidades únicas para todas as instâncias de objetos correspondentes. Para avançar a PCS, construímos um motor de dados escalável que produz um conjunto de dados de alta qualidade com 4M rótulos de conceito únicos, incluindo negativos difíceis, em imagens e vídeos. Nosso modelo consiste em um detector de nível de imagem e um rastreador de vídeo baseado em memória que compartilham um único backbone. O reconhecimento e a localização são desacoplados por meio de uma presença head, o que aumenta a precisão da detecção. O SAM 3 dobra a precisão dos sistemas existentes tanto na PCS de imagem quanto na de vídeo, e melhora as capacidades anteriores do SAM em tarefas de segmentação visual. Tornamos o SAM 3 open source, juntamente com nosso novo benchmark Segment Anything with Concepts (SA-Co) para segmentação de conceitos promptável.*

Este modelo foi contribuído por [yonigozlan](https://huggingface.co/yonigozlan) e [ronghanghu](https://huggingface.co/ronghanghu).

## Exemplo de uso

### Geração automática de máscaras com Pipeline

O Sam3Tracker pode ser usado para geração automática de máscaras, segmentando todos os objetos em uma imagem usando o pipeline `mask-generation`:

```python
from transformers import pipeline

generator = pipeline("mask-generation", model="facebook/sam3", device=0)
image_url = "https://huggingface.co/datasets/hf-internal-testing/sam2-fixtures/resolve/main/truck.jpg"
outputs = generator(image_url, points_per_batch=64)

len(outputs["masks"])  # Number of masks generated
39
```

### Segmentação Básica de Imagens

#### Clique em um único ponto

Você pode segmentar objetos fornecendo um único clique no objeto que deseja segmentar:

```python
from transformers import Sam3TrackerProcessor, Sam3TrackerModel
import torch
from PIL import Image
import requests

model = Sam3TrackerModel.from_pretrained("facebook/sam3", device_map="auto")
processor = Sam3TrackerProcessor.from_pretrained("facebook/sam3")

image_url = "https://huggingface.co/datasets/hf-internal-testing/sam2-fixtures/resolve/main/truck.jpg"
raw_image = Image.open(requests.get(image_url, stream=True).raw).convert("RGB")

input_points = [[[[500, 375]]]]  # Single point click, 4 dimensions (image_dim, object_dim, point_per_object_dim, coordinates)
input_labels = [[[1]]]  # 1 for positive click, 0 for negative click, 3 dimensions (image_dim, object_dim, point_label)

inputs = processor(images=raw_image, input_points=input_points, input_labels=input_labels, return_tensors="pt").to(model.device)

with torch.no_grad():
    outputs = model(**inputs)

masks = processor.post_process_masks(outputs.pred_masks.cpu(), inputs["original_sizes"])[0]

# The model outputs multiple mask predictions ranked by quality score
print(f"Generated {masks.shape[1]} masks with shape {masks.shape}")
Generated 3 masks with shape torch.Size([1, 3, 1500, 2250])
```

#### Vários pontos para refinamento

Você pode fornecer vários pontos para refinar a segmentação:

```python
# Add both positive and negative points to refine the mask
input_points = [[[[500, 375], [1125, 625]]]]  # Multiple points for refinement
input_labels = [[[1, 1]]]  # Both positive clicks

inputs = processor(images=raw_image, input_points=input_points, input_labels=input_labels, return_tensors="pt").to(model.device)

with torch.no_grad():
    outputs = model(**inputs)

masks = processor.post_process_masks(outputs.pred_masks.cpu(), inputs["original_sizes"])[0]
```

#### Entrada de Bounding Box

O Sam3Tracker também aceita entradas de bounding box para segmentação:

```python
# Define bounding box as [x_min, y_min, x_max, y_max]
input_boxes = [[[75, 275, 1725, 850]]]

inputs = processor(images=raw_image, input_boxes=input_boxes, return_tensors="pt").to(model.device)

with torch.no_grad():
    outputs = model(**inputs)

masks = processor.post_process_masks(outputs.pred_masks.cpu(), inputs["original_sizes"])[0]
```

#### Segmentação de múltiplos objetos

Você pode segmentar vários objetos simultaneamente:

```python
# Define points for two different objects
input_points = [[[[500, 375]], [[650, 750]]]]  # Points for two objects in same image
input_labels = [[[1], [1]]]  # Positive clicks for both objects

inputs = processor(images=raw_image, input_points=input_points, input_labels=input_labels, return_tensors="pt").to(model.device)

with torch.no_grad():
    outputs = model(**inputs, multimask_output=False)

# Each object gets its own mask
masks = processor.post_process_masks(outputs.pred_masks.cpu(), inputs["original_sizes"])[0]
print(f"Generated masks for {masks.shape[0]} objects")
Generated masks for 2 objects
```

### Inferência em Lote

#### Imagens em Lote

Processe várias imagens simultaneamente para melhorar a eficiência:

```python
from transformers import Sam3TrackerProcessor, Sam3TrackerModel
import torch
from PIL import Image
import requests

model = Sam3TrackerModel.from_pretrained("facebook/sam3", device_map="auto")
processor = Sam3TrackerProcessor.from_pretrained("facebook/sam3")

# Load multiple images
image_urls = [
    "https://huggingface.co/datasets/hf-internal-testing/sam2-fixtures/resolve/main/truck.jpg",
    "https://huggingface.co/datasets/hf-internal-testing/transformers-synthetic-assets/resolve/main/images/dog_sam.png"
]
raw_images = [Image.open(requests.get(url, stream=True).raw).convert("RGB") for url in image_urls]

# Single point per image
input_points = [[[[500, 375]]], [[[770, 200]]]]  # One point for each image
input_labels = [[[1]], [[1]]]  # Positive clicks for both images

inputs = processor(images=raw_images, input_points=input_points, input_labels=input_labels, return_tensors="pt").to(model.device)

with torch.no_grad():
    outputs = model(**inputs, multimask_output=False)

# Post-process masks for each image
all_masks = processor.post_process_masks(outputs.pred_masks.cpu(), inputs["original_sizes"])
print(f"Processed {len(all_masks)} images, each with {all_masks[0].shape[0]} objects")
Processed 2 images, each with 1 objects
```

#### Objetos em lote por imagem

Segmente múltiplos objetos em cada imagem usando inferência em lote:

```python
# Multiple objects per image - different numbers of objects per image
input_points = [
    [[[500, 375]], [[650, 750]]],  # Truck image: 2 objects
    [[[770, 200]]]  # Dog image: 1 object
]
input_labels = [
    [[1], [1]],  # Truck image: positive clicks for both objects
    [[1]]  # Dog image: positive click for the object
]

inputs = processor(images=raw_images, input_points=input_points, input_labels=input_labels, return_tensors="pt").to(model.device)

with torch.no_grad():
    outputs = model(**inputs, multimask_output=False)

all_masks = processor.post_process_masks(outputs.pred_masks.cpu(), inputs["original_sizes"])
```

#### Imagens em lote com objetos em lote e múltiplos pontos

Trate cenários complexos de lote com múltiplos pontos por objeto:

```python
# Add groceries image for more complex example
groceries_url = "https://huggingface.co/datasets/hf-internal-testing/sam2-fixtures/resolve/main/groceries.jpg"
groceries_image = Image.open(requests.get(groceries_url, stream=True).raw).convert("RGB")
raw_images = [raw_images[0], groceries_image]  # Use truck and groceries images

# Complex batching: multiple images, multiple objects, multiple points per object
input_points = [
    [[[500, 375]], [[650, 750]]],  # Truck image: 2 objects with 1 point each
    [[[400, 300]], [[630, 300], [550, 300]]]  # Groceries image: obj1 has 1 point, obj2 has 2 points
]
input_labels = [
    [[1], [1]],  # Truck image: positive clicks
    [[1], [1, 1]]  # Groceries image: positive clicks for refinement
]

inputs = processor(images=raw_images, input_points=input_points, input_labels=input_labels, return_tensors="pt").to(model.device)

with torch.no_grad():
    outputs = model(**inputs, multimask_output=False)

all_masks = processor.post_process_masks(outputs.pred_masks.cpu(), inputs["original_sizes"])
```

#### Caixas Delimitadoras em Lote

Processe várias imagens com entradas de bounding box:

```python
# Multiple bounding boxes per image (using truck and groceries images)
input_boxes = [
    [[75, 275, 1725, 850], [425, 600, 700, 875], [1375, 550, 1650, 800], [1240, 675, 1400, 750]],  # Truck image: 4 boxes
    [[450, 170, 520, 350], [350, 190, 450, 350], [500, 170, 580, 350], [580, 170, 640, 350]]  # Groceries image: 4 boxes
]

# Update images for this example
raw_images = [raw_images[0], groceries_image]  # truck and groceries

inputs = processor(images=raw_images, input_boxes=input_boxes, return_tensors="pt").to(model.device)

with torch.no_grad():
    outputs = model(**inputs, multimask_output=False)

all_masks = processor.post_process_masks(outputs.pred_masks.cpu(), inputs["original_sizes"])
print(f"Processed {len(input_boxes)} images with {len(input_boxes[0])} and {len(input_boxes[1])} boxes respectively")
Processed 2 images with 4 and 4 boxes respectively
```

### Usando Máscaras Anteriores como Entrada

O Sam3Tracker pode usar máscaras de previsões anteriores como entrada para refinar a segmentação:

```python
# Get initial segmentation
input_points = [[[[500, 375]]]]
input_labels = [[[1]]]
inputs = processor(images=raw_image, input_points=input_points, input_labels=input_labels, return_tensors="pt").to(model.device)

with torch.no_grad():
    outputs = model(**inputs)

# Use the best mask as input for refinement
mask_input = outputs.pred_masks[:, :, torch.argmax(outputs.iou_scores.squeeze())]

# Add additional points with the mask input
new_input_points = [[[[500, 375], [450, 300]]]]
new_input_labels = [[[1, 1]]]
inputs = processor(
    input_points=new_input_points,
    input_labels=new_input_labels,
    original_sizes=inputs["original_sizes"],
    return_tensors="pt",
).to(model.device)

with torch.no_grad():
    refined_outputs = model(
        **inputs,
        input_masks=mask_input,
        image_embeddings=outputs.image_embeddings,
        multimask_output=False,
    )
```

## Sam3TrackerConfig[[transformers.Sam3TrackerConfig]]

#### transformers.Sam3TrackerConfig[[transformers.Sam3TrackerConfig]]

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

[Origem](https://github.com/huggingface/transformers/blob/main/src/transformers/models/sam3_tracker/configuration_sam3_tracker.py#L96)

**Parâmetros:**

vision_config (`Union[dict, ~configuration_utils.PreTrainedConfig]`, *opcional*) : O objeto de configuração ou dicionário do backbone de visão.

prompt_encoder_config (Union[`dict`, `Sam3TrackerPromptEncoderConfig`], *opcional*) : Dicionário de opções de configuração usadas para inicializar [Sam3TrackerPromptEncoderConfig](/docs/transformers/main/pt/model_doc/sam3_tracker#transformers.Sam3TrackerPromptEncoderConfig).

mask_decoder_config (Union[`dict`, `Sam3TrackerMaskDecoderConfig`], *opcional*) : Dicionário de opções de configuração usadas para inicializar [Sam3TrackerMaskDecoderConfig](/docs/transformers/main/pt/model_doc/sam3_tracker#transformers.Sam3TrackerMaskDecoderConfig).

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

Esta é a classe de configuração para armazenar a configuração de um Sam3TrackerModel. Ela é usada para instanciar um modelo Sam3 Tracker 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/sam3](https://huggingface.co/facebook/sam3)

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.

Exemplo:

```python
>>> from transformers import (
...     Sam3TrackerVisionConfig,
...     Sam3TrackerPromptEncoderConfig,
...     Sam3TrackerMaskDecoderConfig,
...     Sam3TrackerModel,
... )

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

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

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

>>> # We can also initialize a Sam3TrackerConfig from a Sam3TrackerVisionConfig, Sam3TrackerPromptEncoderConfig, and Sam3TrackerMaskDecoderConfig
>>> # Initializing SAM3_TRACKER vision encoder, memory attention, and memory encoder configurations
>>> vision_config = Sam3TrackerVisionConfig()
>>> prompt_encoder_config = Sam3TrackerPromptEncoderConfig()
>>> mask_decoder_config = Sam3TrackerMaskDecoderConfig()

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

## Sam3TrackerPromptEncoderConfig[[transformers.Sam3TrackerPromptEncoderConfig]]

#### transformers.Sam3TrackerPromptEncoderConfig[[transformers.Sam3TrackerPromptEncoderConfig]]

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

[Origem](https://github.com/huggingface/transformers/blob/main/src/transformers/models/sam3_tracker/configuration_sam3_tracker.py#L31)

**Parâmetros:**

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

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

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

mask_input_channels (`int`, *opcional*, padrão 16) : O número de canais a serem enviados para o módulo `MaskDecoder`.

num_point_embeddings (`int`, *opcional*, padrão 4) : O número de embeddings de pontos a serem usados.

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

layer_norm_eps (`float`, *opcional*, padrão `1e-06`) : O epsilon usado pelas camadas de normalização de camada.

scale (`float`, *opcional*, padrão 1) : O fator de escala para o codificador de prompt.

Esta é a classe de configuração para armazenar a configuração de um Sam3TrackerModel. Ela é usada para instanciar um modelo Sam3 Tracker 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/sam3](https://huggingface.co/facebook/sam3)

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.

## Sam3TrackerMaskDecoderConfig[[transformers.Sam3TrackerMaskDecoderConfig]]

#### transformers.Sam3TrackerMaskDecoderConfig[[transformers.Sam3TrackerMaskDecoderConfig]]

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

[Origem](https://github.com/huggingface/transformers/blob/main/src/transformers/models/sam3_tracker/configuration_sam3_tracker.py#L57)

**Parâmetros:**

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

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

mlp_dim (`int`, *opcional*, padrão 2048) : A dimensão do MLP no transformer bidirecional.

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

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

attention_downsample_rate (`int`, *opcional*, padrão 2) : A taxa de downsampling para as camadas de atenção.

num_multimask_outputs (`int`, *opcional*, padrão 3) : O número de saídas multimask.

iou_head_depth (`int`, *opcional*, padrão 3) : A profundidade da cabeça de IoU.

iou_head_hidden_dim (`int`, *opcional*, padrão 256) : A dimensão oculta da cabeça de IoU.

dynamic_multimask_via_stability (`bool`, *opcional*, padrão `True`) : Se deve usar a multimáscara dinâmica via estabilidade.

dynamic_multimask_stability_delta (`float`, *opcional*, padrão 0.05) : O delta de estabilidade para a multimáscara dinâmica.

dynamic_multimask_stability_thresh (`float`, *opcional*, padrão 0.98) : O limiar de estabilidade para a multimáscara dinâmica.

Esta é a classe de configuração para armazenar a configuração de um Sam3TrackerModel. Ela é usada para instanciar um modelo Sam3 Tracker 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/sam3](https://huggingface.co/facebook/sam3)

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.

## Sam3TrackerProcessor[[transformers.Sam3TrackerProcessor]]

#### transformers.Sam3TrackerProcessor[[transformers.Sam3TrackerProcessor]]

```python
transformers.Sam3TrackerProcessor(image_processor, target_size: int | None = None, point_pad_value: int = -10, **kwargs)
```

[Origem](https://github.com/huggingface/transformers/blob/main/src/transformers/models/sam3_tracker/processing_sam3_tracker.py#L36)

**Parâmetros:**

image_processor (`Sam3ImageProcessor`) : O processador de imagem é uma entrada obrigatória.

target_size (`int`, *opcional*) : O tamanho alvo (em pixels) para normalizar pontos de entrada e caixas delimitadoras. Se não for fornecido, o padrão é a configuração de tamanho do processador de imagem. Todas as coordenadas de entrada (pontos e caixas) são normalizadas para esse tamanho antes de serem passadas ao modelo. Isso garante uma representação consistente das coordenadas, independentemente das dimensões originais da imagem.

point_pad_value (`int`, *opcional*, padrão -10) : O valor usado para preencher os pontos de entrada ao agrupar sequências de comprimentos diferentes. Esse valor é usado para marcar as posições preenchidas e é preservado durante a normalização de coordenadas.

Constrói um Sam3TrackerProcessor que encapsula um processador de imagem em um único processador.

[Sam3TrackerProcessor](/docs/transformers/main/pt/model_doc/sam3_tracker#transformers.Sam3TrackerProcessor) oferece todas as funcionalidades de [Sam3ImageProcessor](/docs/transformers/main/pt/model_doc/sam3#transformers.Sam3ImageProcessor). Consulte [~Sam3ImageProcessor](/docs/transformers/main/pt/model_doc/sam3#transformers.Sam3ImageProcessor) para mais informações.

#### __call__[[transformers.Sam3TrackerProcessor.__call__]]

```python
__call__(images: typing.Union[ForwardRef('PIL.Image.Image'), numpy.ndarray, ForwardRef('torch.Tensor'), list['PIL.Image.Image'], list[numpy.ndarray], list['torch.Tensor'], NoneType] = None, 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, input_points: typing.Union[list[list[list[list[float]]]], torch.Tensor, NoneType] = None, input_labels: typing.Union[list[list[list[int]]], torch.Tensor, NoneType] = None, input_boxes: typing.Union[list[list[list[float]]], torch.Tensor, NoneType] = None, original_sizes: typing.Union[list[list[float]], torch.Tensor, NoneType] = None, return_tensors: str | transformers.utils.generic.TensorType | None = None, **kwargs)
```

[Origem](https://github.com/huggingface/transformers/blob/main/src/transformers/models/sam3_tracker/processing_sam3_tracker.py#L52)

**Parâmetros:**

images (`Union[PIL.Image.Image, numpy.ndarray, torch.Tensor, list[PIL.Image.Image], list[numpy.ndarray], list[torch.Tensor]]`, *opcional*) : 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 processados.

input_points (`list[list[list[list[float]]]]`, `torch.Tensor`, *opcional*) : Os pontos a serem adicionados ao frame.

input_labels (`list[list[list[int]]]`, `torch.Tensor`, *opcional*) : Os rótulos dos pontos.

input_boxes (`list[list[list[float]]]`, `torch.Tensor`, *opcional*) : As caixas delimitadoras a serem adicionadas ao quadro.

original_sizes (`list[list[float]]`, `torch.Tensor`, *opcional*) : Os tamanhos originais das imagens.

return_tensors (`Union[str, ~utils.generic.TensorType]`, *opcional*) : Se definido, retornará tensors de um framework específico. Os valores aceitos são:  - `'pt'`: Retorna objetos `torch.Tensor` do PyTorch. - `'np'`: Retorna objetos `np.ndarray` do NumPy.

**Retorna:** Um [BatchEncoding](/docs/transformers/main/pt/main_classes/tokenizer#transformers.BatchEncoding) com os seguintes campos

- `pixel_values` (`torch.Tensor`): A(s) imagem(ns) processada(s).
- `original_sizes` (`list[list[float]]`): Os tamanhos originais das imagens.
- `labels` (`torch.Tensor`): Os mapas de segmentação processados (se fornecidos).
- `input_points` (`torch.Tensor`): Os pontos processados.
- `input_labels` (`torch.Tensor`): Os rótulos processados.
- `input_boxes` (`torch.Tensor`): As caixas delimitadoras processadas.

#### post_process_masks[[transformers.Sam3TrackerProcessor.post_process_masks]]

```python
post_process_masks(masks, original_sizes, mask_threshold = 0.0, binarize = True, max_hole_area = 0.0, max_sprinkle_area = 0.0, apply_non_overlapping_constraints = False, **kwargs)
```

[Origem](https://github.com/huggingface/transformers/blob/main/src/transformers/models/sam3_tracker/processing_sam3_tracker.py#L458)

**Parâmetros:**

masks (`Union[List[torch.Tensor], List[np.ndarray]]`) : Máscaras em lote do mask_decoder no formato (batch_size, num_channels, height, width).

original_sizes (`Union[torch.Tensor, List[Tuple[int,int]]]`) : Os tamanhos originais de cada imagem antes de serem redimensionadas para o formato de entrada esperado pelo modelo, no formato (altura, largura).

mask_threshold (`float`, *opcional*, padrão 0.0) : Limiar para operações de binarização e pós-processamento.

binarize (`bool`, *opcional*, padrão `True`) : Se deve binarizar as máscaras.

max_hole_area (`float`, *opcional*, padrão 0.0) : A área máxima de um furo a ser preenchido.

max_sprinkle_area (`float`, *opcional*, padrão 0.0) : A área máxima de um sprinkle para preencher.

apply_non_overlapping_constraints (`bool`, *opcional*, padrão `False`) : Se deve aplicar restrições de não sobreposição às máscaras.

**Retorna:** (`torch.Tensor`)

Máscaras em lote no formato batch_size, num_channels, height, width), onde (height, width) é dado por original_size.

Remova o padding e redimensione as máscaras para o tamanho original da imagem.

## Sam3TrackerModel[[transformers.Sam3TrackerModel]]

#### transformers.Sam3TrackerModel[[transformers.Sam3TrackerModel]]

```python
transformers.Sam3TrackerModel(config: Sam3TrackerConfig)
```

[Origem](https://github.com/huggingface/transformers/blob/main/src/transformers/models/sam3_tracker/modeling_sam3_tracker.py#L772)

**Parâmetros:**

config ([Sam3TrackerConfig](/docs/transformers/main/pt/model_doc/sam3_tracker#transformers.Sam3TrackerConfig)) : 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.

Segment Anything Model 2 (SAM 2) para gerar máscaras de segmentação, dado uma imagem de entrada e pontos e rótulos, caixas ou máscaras de entrada.

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.Sam3TrackerModel.forward]]

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

[Origem](https://github.com/huggingface/transformers/blob/main/src/transformers/models/sam3_tracker/modeling_sam3_tracker.py#L886)

**Parâmetros:**

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

input_points (`torch.Tensor` de forma `(batch_size, num_points, 2)`) : Pontos espaciais 2D de entrada, usados pelo codificador de prompt para codificar o prompt. Geralmente, isso resulta em muito melhores resultados. Os pontos podem ser obtidos passando uma lista de listas de listas para o processador, que criará os correspondentes `torch` tensores de dimensão 4. A primeira dimensão é o tamanho do lote de imagens, a segunda dimensão é o tamanho do lote de pontos (ou seja, quantas máscaras de segmentação queremos que o modelo preveja por ponto de entrada), a terceira dimensão é o número de pontos por máscara de segmentação (é possível passar múltiplos pontos para uma única máscara) e a última dimensão são as coordenadas x (vertical) e y (horizontal) do ponto. Se um número diferente de pontos for passado para cada imagem ou para cada máscara, o processador criará pontos "PAD" que corresponderão à coordenada (0, 0), e o cálculo do embedding será ignorado para esses pontos usando os rótulos.

input_labels (`torch.LongTensor` de forma `(batch_size, point_batch_size, num_points)`) : Rótulos de entrada para os pontos, usados pelo codificador de prompt para codificar o prompt. De acordo com a implementação oficial, existem 3 tipos de rótulos  - `1`: o ponto contém o objeto de interesse - `0`: o ponto não contém o objeto de interesse - `-1`: o ponto corresponde ao fundo  Adicionamos o rótulo:  - `-10`: o ponto é um ponto de preenchimento (padding) e, portanto, deve ser ignorado pelo codificador de prompt  Os rótulos de preenchimento devem ser aplicados automaticamente pelo processador.

input_boxes (`torch.Tensor` de forma `(batch_size, num_boxes, 4)`) : Caixas de entrada para os pontos, usadas pelo codificador de prompt para codificar o prompt. Geralmente resulta em máscaras geradas muito melhores. As caixas podem ser obtidas passando uma lista de listas de listas para o processador, que gerará um tensor `torch`, com cada dimensão correspondendo, respectivamente, ao tamanho do lote de imagens, ao número de caixas por imagem e às coordenadas do ponto superior esquerdo e do ponto inferior direito da caixa. Na ordem (`x1`, `y1`, `x2`, `y2`):  - `x1`: a coordenada x do ponto superior esquerdo da caixa de entrada - `y1`: a coordenada y do ponto superior esquerdo da caixa de entrada - `x2`: a coordenada x do ponto inferior direito da caixa de entrada - `y2`: a coordenada y do ponto inferior direito da caixa de entrada

input_masks (`torch.Tensor` de forma `(batch_size, image_size, image_size)`) : O modelo SAM também aceita máscaras de segmentação como entrada. A máscara será incorporada pelo codificador de prompt para gerar uma incorporação correspondente, que será fornecida posteriormente ao decodificador de máscara. Essas máscaras precisam ser fornecidas manualmente pelo usuário e precisam ter a forma (`batch_size`, `image_size`, `image_size`).

image_embeddings (`torch.Tensor` de forma `(batch_size, output_channels, window_size, window_size)`) : Embebimentos de imagem, usados pelo decodificador de máscaras para gerar máscaras e pontuações de iou. Para um cálculo mais eficiente em termos de memória, os usuários podem primeiro recuperar os embebimentos de imagem usando o método `get_image_embeddings` e, em seguida, fornecê-los ao método `forward` em vez de fornecer os `pixel_values`.

multimask_output (`bool`, *opcional*) : Na implementação e no artigo originais, o modelo sempre produz 3 máscaras por imagem (ou por ponto / por bounding box, quando aplicável). No entanto, é possível produzir apenas uma única máscara, que corresponde à máscara "melhor", especificando `multimask_output=False`.

attention_similarity (`torch.Tensor`, *opcional*) : Tensor de similaridade de atenção, a ser fornecido ao decodificador de máscara para atenção guiada por alvo, caso o modelo seja usado para personalização, conforme introduzido em [PerSAM](https://huggingface.co/papers/2305.03048).

target_embedding (`torch.Tensor`, *opcional*) : Incorporação do conceito-alvo, a ser fornecida ao decodificador de máscara para prompting semântico-alvo, caso o modelo seja usado para personalização, conforme introduzido em [PerSAM](https://huggingface.co/papers/2305.03048).

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

Um `Sam3TrackerImageSegmentationOutput` 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 ([Sam3TrackerConfig](/docs/transformers/main/pt/model_doc/sam3_tracker#transformers.Sam3TrackerConfig)) e das entradas.

O método forward do [Sam3TrackerModel](/docs/transformers/main/pt/model_doc/sam3_tracker#transformers.Sam3TrackerModel) 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.

- **iou_scores** (`torch.Tensor` de forma `(batch_size, point_batch_size, num_masks)`) -- As pontuações de Interseção sobre União (IoU) das máscaras previstas.
- **pred_masks** (`torch.Tensor` de forma `(batch_size, point_batch_size, num_masks, height, width)`) -- As máscaras de baixa resolução previstas. Este é um alias para `low_res_masks`. Essas máscaras precisam ser pós-processadas pelo processor para serem trazidas ao tamanho original da imagem.
- **object_score_logits** (`torch.Tensor` de forma `(batch_size, point_batch_size, 1)`) -- Logits para a pontuação do objeto, indicando se um objeto está presente.
- **image_embeddings** (`tuple(torch.Tensor)`) -- Os recursos do FPN, que são usados pelo decodificador de máscaras. Esta é uma tupla de `torch.Tensor` em que cada tensor tem a forma `(batch_size, channels, height, width)`.
- **vision_hidden_states** (`tuple(torch.Tensor)`, *opcional*, retornado quando `output_hidden_states=True`) -- Tupla de `torch.Tensor` (um para a saída de cada estágio) com forma `(batch_size, height, width, hidden_size)`. Estados ocultos do modelo de visão na saída de cada estágio.
- **vision_attentions** (`tuple(torch.Tensor)`, *opcional*, retornado quando `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 do modelo de visão.
- **mask_decoder_attentions** (`tuple(torch.Tensor)`, *opcional*, retornado quando `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 do decodificador de máscara.

Exemplo:

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

>>> model = AutoModel.from_pretrained("danelcsb/sam3_tracker.1_hiera_tiny")
>>> processor = AutoProcessor.from_pretrained("danelcsb/sam3_tracker.1_hiera_tiny")

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

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

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

#### get_image_features[[transformers.Sam3TrackerModel.get_image_features]]

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

[Origem](https://github.com/huggingface/transformers/blob/main/src/transformers/models/sam3_tracker/modeling_sam3_tracker.py#L1064)

**Parâmetros:**

pixel_values (`torch.Tensor`) : Valores de pixels de entrada com forma `(batch_size, num_channels, height, width)`.

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

Um `Sam3TrackerVisionEncoderOutput` 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 ([Sam3TrackerConfig](/docs/transformers/main/pt/model_doc/sam3_tracker#transformers.Sam3TrackerConfig)) e das entradas.

- **last_hidden_state** (`torch.Tensor` de forma `(batch_size, height, width, 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.
- **fpn_hidden_states** (`tuple(torch.Tensor)`) -- Tupla de `torch.Tensor` (um para cada nível de recurso, da resolução mais alta para a mais baixa) com forma `(batch_size, hidden_size, height, width)`. Mapas de recursos do pescoço da Feature Pyramid Network.
- **fpn_position_encoding** (`tuple(torch.Tensor)`) -- Tupla de `torch.Tensor` (um para cada nível de recurso, da resolução mais alta para a mais baixa) com forma `(batch_size, hidden_size, height, width)`. Codificações posicionais correspondentes às `fpn_hidden_states`.

Exemplo:

```python
```

## Sam3TrackerPreTrainedModel[[transformers.Sam3TrackerPreTrainedModel]]

#### transformers.Sam3TrackerPreTrainedModel[[transformers.Sam3TrackerPreTrainedModel]]

```python
transformers.Sam3TrackerPreTrainedModel(config: PreTrainedConfig, *inputs, **kwargs)
```

[Origem](https://github.com/huggingface/transformers/blob/main/src/transformers/models/sam3_tracker/modeling_sam3_tracker.py#L117)

**Parâmetros:**

config ([PreTrainedConfig](/docs/transformers/main/pt/main_classes/configuration#transformers.PreTrainedConfig)) : 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.

Segment Anything Model 3 (SAM 3) para gerar máscaras de segmentação, dado uma imagem de entrada e pontos e rótulos, caixas ou máscaras de entrada.

#### forward[[transformers.Sam3TrackerPreTrainedModel.forward]]

```python
forward(*args, **kwargs)
```

Um valor simulado para um caminho pontilhado (por exemplo, `torch.float32`): as cadeias de acesso a atributos e as chamadas se comportam como decoradores de passagem, o `repr` é o caminho pontilhado, e o uso como classe base substitui uma base de `type` simples (PEP 560 `__mro_entries__`), de modo que as subclasses reais mantêm um metaclass normal e o `inspect.signature` lê o `__init__` real delas, em vez do de um mock.