Transformers documentation

SAM3 Tracker

Transformers

Comece agora

Transformers Instalação Início rápido

Classes base

Modelos

Pré-processadores

Inferência

Pipeline API

API de geração

Otimização

Conversar com modelos

Serving

Treinamento

Comece agora

Personalização

Ajuste fino de parâmetros eficientes

Desempenho

Treinamento distribuído

Hardware

Quantização

Integrações com o ecossistema

Recursos

API

Principais classes

Modelos

Modelos de texto

Modelos de visão

Modelos de áudio

Modelos de vídeo

Modelos multimodais

Modelos de aprendizado por reforço

Modelos de séries temporais

Helpers internos

Referência

Join the Hugging Face community

and get access to the augmented documentation experience

Collaborate on models, datasets and Spaces

Faster examples with accelerated inference

Switch between documentation themes

to get started

Este modelo foi contribuído para o Hugging Face Transformers em 19/11/2025.

SAM3 Tracker

Visão geral

O SAM3 (Segment Anything Model 3) foi introduzido em 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 Conceito 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 de 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. Abre o código-fonte do SAM 3 junto com nosso novo benchmark Segment Anything with Concepts (SA-Co) para segmentação de conceito promptável.

Este modelo foi contribuído por yonigozlan e 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:

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:

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:

# 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:

# 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:

# 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:

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:

# 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:

# 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:

# 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:

# 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

classe transformers.Sam3TrackerConfig

< source >

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 usado para inicializar Sam3TrackerPromptEncoderConfig.
mask_decoder_config (Union[dict, Sam3TrackerMaskDecoderConfig], opcional) — Dicionário de opções de configuração usado para inicializar 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

Os objetos de configuração herdam de PreTrainedConfig e podem ser usados para controlar as saídas do modelo. Consulte a documentação de PreTrainedConfig para mais informações.

Exemplo:

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

classe transformers.Sam3TrackerPromptEncoderConfig

< source >

( transformers_version: str | None = Nonearchitectures: list[str] | None = Noneoutput_hidden_states: bool | None = Falsereturn_dict: bool | None = Truedtype: str | torch.dtype | None = Nonechunk_size_feed_forward: int = 0is_encoder_decoder: bool = Falseid2label: dict[int, str] | dict[str, str] | None = Nonelabel2id: dict[str, int] | dict[str, str] | None = Noneproblem_type: Literal['regression', 'single_label_classification', 'multi_label_classification'] | None = Nonehidden_size: int = 256image_size: int | list[int] | tuple[int, int] = 1008patch_size: int | list[int] | tuple[int, int] = 14mask_input_channels: int = 16num_point_embeddings: int = 4hidden_act: str = 'gelu'layer_norm_eps: float = 1e-06scale: int = 1 )

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 fornecidos ao módulo MaskDecoder.
num_point_embeddings (int, opcional, padrão 4) — O número de incorporações de pontos a serem usadas.
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) — Fator de escala para o codificador de prompt.

Os objetos de configuração herdam de PreTrainedConfig e podem ser usados para controlar as saídas do modelo. Consulte a documentação de PreTrainedConfig para mais informações.

Sam3TrackerMaskDecoderConfig

classe transformers.Sam3TrackerMaskDecoderConfig

< source >

( transformers_version: str | None = Nonearchitectures: list[str] | None = Noneoutput_hidden_states: bool | None = Falsereturn_dict: bool | None = Truedtype: str | torch.dtype | None = Nonechunk_size_feed_forward: int = 0is_encoder_decoder: bool = Falseid2label: dict[int, str] | dict[str, str] | None = Nonelabel2id: dict[str, int] | dict[str, str] | None = Noneproblem_type: Literal['regression', 'single_label_classification', 'multi_label_classification'] | None = Nonehidden_size: int = 256hidden_act: str = 'gelu'mlp_dim: int = 2048num_hidden_layers: int = 2num_attention_heads: int = 8attention_downsample_rate: int = 2num_multimask_outputs: int = 3iou_head_depth: int = 3iou_head_hidden_dim: int = 256dynamic_multimask_via_stability: bool = Truedynamic_multimask_stability_delta: float = 0.05dynamic_multimask_stability_thresh: float = 0.98 )

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 de duas vias.
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 dynamic multimask via stability.
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 multimask dinâmica.

Os objetos de configuração herdam de PreTrainedConfig e podem ser usados para controlar as saídas do modelo. Consulte a documentação de PreTrainedConfig para mais informações.

Sam3TrackerProcessor

classe transformers.Sam3TrackerProcessor

< source >

( image_processortarget_size: int | None = Nonepoint_pad_value: int = -10**kwargs )

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 oferece todas as funcionalidades de Sam3ImageProcessor. Consulte ~Sam3ImageProcessor para mais informações.

call

< source >

( images: typing.Union[ForwardRef('PIL.Image.Image'), numpy.ndarray, ForwardRef('torch.Tensor'), list['PIL.Image.Image'], list[numpy.ndarray], list['torch.Tensor'], NoneType] = Nonesegmentation_maps: typing.Union[ForwardRef('PIL.Image.Image'), numpy.ndarray, ForwardRef('torch.Tensor'), list['PIL.Image.Image'], list[numpy.ndarray], list['torch.Tensor'], NoneType] = Noneinput_points: typing.Union[list[list[list[list[float]]]], torch.Tensor, NoneType] = Noneinput_labels: typing.Union[list[list[list[int]]], torch.Tensor, NoneType] = Noneinput_boxes: typing.Union[list[list[list[float]]], torch.Tensor, NoneType] = Noneoriginal_sizes: typing.Union[list[list[float]], torch.Tensor, NoneType] = Nonereturn_tensors: str | transformers.utils.generic.TensorType | None = None**kwargs ) → A BatchEncoding with the following fields

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 passar 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 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

< source >

( masksoriginal_sizesmask_threshold = 0.0binarize = Truemax_hole_area = 0.0max_sprinkle_area = 0.0apply_non_overlapping_constraints = False**kwargs ) → (torch.Tensor)

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 as máscaras devem ser binarizadas.
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, em que (height, width) é dado por original_size.

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

Sam3TrackerModel

classe transformers.Sam3TrackerModel

< source >

( config: Sam3TrackerConfig )

Parâmetros

config (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() 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. 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 do PyTorch. Use-o como um Módulo PyTorch regular e consulte a documentação do PyTorch para todos os assuntos relacionados ao uso geral e ao comportamento.

forward

< source >

( pixel_values: typing.Optional[torch.Tensor] = Noneinput_points: typing.Optional[torch.Tensor] = Noneinput_labels: typing.Optional[torch.LongTensor] = Noneinput_boxes: typing.Optional[torch.Tensor] = Noneinput_masks: typing.Optional[torch.LongTensor] = Noneimage_embeddings: typing.Optional[torch.Tensor] = Nonemultimask_output: bool = Trueattention_similarity: typing.Optional[torch.Tensor] = Nonetarget_embedding: typing.Optional[torch.Tensor] = None**kwargs: *<class 'transformers.utils.generic.TransformersKwargs'> ) → Sam3TrackerImageSegmentationOutput or tuple(torch.Tensor)

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. Consulte Sam3ImageProcessor.call() para mais detalhes (Sam3TrackerProcessor usa Sam3ImageProcessor para processar as 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 tensores torch 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 desejamos 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 é um ponto que contém o objeto de interesse
- 0: o ponto é um ponto que 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, portanto deve ser ignorado pelo codificador de prompt
Os rótulos de preenchimento devem ser feitos automaticamente pelo processador.
input_boxes (torch.Tensor de forma (batch_size, num_boxes, 4)) — Caixas de entrada para os pontos, usadas pelo prompt encoder para codificar o prompt. Geralmente, isso resulta em máscaras geradas muito melhores. As caixas podem ser obtidas passando uma lista de listas de listas para o processor, que gerará um torch tensor, em que cada dimensão corresponde, 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)) — Incorporações de imagem, usadas 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 as incorporações de imagem usando o método get_image_embeddings e, em seguida, fornecê-las 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.
target_embedding (torch.Tensor, opcional) — Embedding do conceito alvo, a ser fornecido ao decodificador de máscara para prompting semântico do alvo, caso o modelo seja usado para personalização, conforme introduzido em PerSAM.

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) e das entradas.

O método forward do 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 forma (batch_size, num_heads, sequence_length, sequence_length). Pesos de atenção do decodificador de máscara.

Exemplo:

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

< source >

( pixel_values: Tensor**kwargs: *<class 'transformers.utils.generic.TransformersKwargs'> ) → Sam3TrackerVisionEncoderOutput or tuple(torch.Tensor)

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) 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 através das camadas usadas para a tarefa de pré-treinamento auxiliar. Por exemplo, para a família de modelos BERT, isso retorna o token de classificação após o processamento através de 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) de 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 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 nos cabeçalhos 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:

Sam3TrackerPreTrainedModel

classe transformers.Sam3TrackerPreTrainedModel

< source >

( config: PreTrainedConfig*inputs**kwargs )

Parâmetros

config (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() 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

( *args**kwargs )

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

Update on GitHub

←SAM2 Sapiens2→