Transformers documentation

SAM3 Rastreador de Vídeo

Hugging Face's logo
Join the Hugging Face community

and get access to the augmented documentation experience

to get started

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

SAM3 Rastreador de Vídeo

SDPA FlashAttention

Visão geral

O SAM3 (Segment Anything Model 3) foi introduzido em SAM 3: Segment Anything with Concepts.

O Sam3TrackerVideo executa Segmentação Visual Promptável (PVS) em vídeos. O PVS utiliza prompts visuais interativos (pontos, caixas, máscaras) ou entradas de texto para rastrear uma instância de objeto específica por prompt ao longo dos quadros do vídeo.

Sam3TrackerVideo é uma versão atualizada do SAM2 Video 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

Segmentação e Rastreamento de Vídeo

Rastreamento básico de vídeo

from transformers import Sam3TrackerVideoModel, Sam3TrackerVideoProcessor
import torch

model = Sam3TrackerVideoModel.from_pretrained("facebook/sam3", device_map="auto")
processor = Sam3TrackerVideoProcessor.from_pretrained("facebook/sam3")

# Load video frames (example assumes you have a list of PIL Images)
# video_frames = [Image.open(f"frame_{i:05d}.jpg") for i in range(num_frames)]

# For this example, we'll use the video loading utility
from transformers.video_utils import load_video
video_url = "https://huggingface.co/datasets/hf-internal-testing/sam2-fixtures/resolve/main/bedroom.mp4"
video_frames, _ = load_video(video_url)

# Initialize video inference session
inference_session = processor.init_video_session(
    video=video_frames,
    inference_device=device,
)

# Add click on first frame to select object
ann_frame_idx = 0
ann_obj_id = 1
points = [[[[210, 350]]]]
labels = [[[1]]]

processor.add_inputs_to_inference_session(
    inference_session=inference_session,
    frame_idx=ann_frame_idx,
    obj_ids=ann_obj_id,
    input_points=points,
    input_labels=labels,
)

# Segment the object on the first frame (optional, you can also propagate the masks through the video directly)
outputs = model(
    inference_session=inference_session,
    frame_idx=ann_frame_idx,
)
video_res_masks = processor.post_process_masks(
    [outputs.pred_masks], original_sizes=[[inference_session.video_height, inference_session.video_width]], binarize=False
)[0]
print(f"Segmentation shape: {video_res_masks.shape}")
Segmentation shape: torch.Size([1, 1, 480, 854])

# Propagate through the entire video
video_segments = {}
for sam3_tracker_video_output in model.propagate_in_video_iterator(inference_session):
    video_res_masks = processor.post_process_masks(
        [sam3_tracker_video_output.pred_masks], original_sizes=[[inference_session.video_height, inference_session.video_width]], binarize=False
    )[0]
    video_segments[sam3_tracker_video_output.frame_idx] = video_res_masks

print(f"Tracked object through {len(video_segments)} frames")
Tracked object through 180 frames

Rastreamento de Vídeo Multi-Objeto

Rastreie vários objetos simultaneamente entre os quadros de um vídeo:

# Reset for new tracking session
inference_session.reset_inference_session()

# Add multiple objects on the first frame
ann_frame_idx = 0
obj_ids = [2, 3]
input_points = [[[[200, 300]], [[400, 150]]]]  # Points for two objects (batched)
input_labels = [[[1], [1]]]

processor.add_inputs_to_inference_session(
    inference_session=inference_session,
    frame_idx=ann_frame_idx,
    obj_ids=obj_ids,
    input_points=input_points,
    input_labels=input_labels,
)

# Get masks for both objects on first frame (optional, you can also propagate the masks through the video directly)
outputs = model(
    inference_session=inference_session,
    frame_idx=ann_frame_idx,
)

# Propagate both objects through video
video_segments = {}
for sam3_tracker_video_output in model.propagate_in_video_iterator(inference_session):
    video_res_masks = processor.post_process_masks(
        [sam3_tracker_video_output.pred_masks], original_sizes=[[inference_session.video_height, inference_session.video_width]], binarize=False
    )[0]
    video_segments[sam3_tracker_video_output.frame_idx] = {
        obj_id: video_res_masks[i]
        for i, obj_id in enumerate(inference_session.obj_ids)
    }

print(f"Tracked {len(inference_session.obj_ids)} objects through {len(video_segments)} frames")
Tracked 2 objects through 180 frames

Refinamento da segmentação de vídeo

Você pode adicionar cliques adicionais em qualquer quadro para refinar o rastreamento:

# Add refinement click on a later frame
refine_frame_idx = 50
ann_obj_id = 2  # Refining first object
points = [[[[220, 280]]]]  # Additional point
labels = [[[1]]]  # Positive click

processor.add_inputs_to_inference_session(
    inference_session=inference_session,
    frame_idx=refine_frame_idx,
    obj_ids=ann_obj_id,
    input_points=points,
    input_labels=labels,
)

# Re-propagate with the additional information
video_segments = {}
for sam3_tracker_video_output in model.propagate_in_video_iterator(inference_session):
    video_res_masks = processor.post_process_masks(
        [sam3_tracker_video_output.pred_masks], original_sizes=[[inference_session.video_height, inference_session.video_width]], binarize=False
    )[0]
    video_segments[sam3_tracker_video_output.frame_idx] = video_res_masks

Inferência de Vídeo em Streaming

Para aplicações em tempo real, o Sam3TrackerVideo suporta o processamento de quadros de vídeo à medida que chegam:

# Initialize session for streaming
inference_session = processor.init_video_session(
    inference_device=device,
)

# Process frames one by one
for frame_idx, frame in enumerate(video_frames[:10]):  # Process first 10 frames
    inputs = processor(images=frame, device=device, return_tensors="pt").to(model.device)
...
    if frame_idx == 0:
        # Add point input on first frame
        processor.add_inputs_to_inference_session(
            inference_session=inference_session,
            frame_idx=0,
            obj_ids=1,
            input_points=[[[[210, 350], [250, 220]]]],
            input_labels=[[[1, 1]]],
            original_size=inputs.original_sizes[0], # need to be provided when using streaming video inference
        )
...
    # Process current frame
    sam3_tracker_video_output = model(inference_session=inference_session, frame=inputs.pixel_values[0])
...
    video_res_masks = processor.post_process_masks(
        [sam3_tracker_video_output.pred_masks], original_sizes=inputs.original_sizes, binarize=False
    )[0]
    print(f"Frame {frame_idx}: mask shape {video_res_masks.shape}")

Processamento em Lote de Vídeos para Múltiplos Objetos

Rastreie vários objetos simultaneamente em um vídeo adicionando todos de uma vez:

# Initialize video session
inference_session = processor.init_video_session(
    video=video_frames,
    inference_device=device,
)

# Add multiple objects on the first frame using batch processing
ann_frame_idx = 0
obj_ids = [2, 3]  # Track two different objects
input_points = [
    [[[200, 300], [230, 250], [275, 175]], [[400, 150]]]
]  # Object 2: 3 points (2 positive, 1 negative); Object 3: 1 point
input_labels = [
    [[1, 1, 0], [1]]
]  # Object 2: positive, positive, negative; Object 3: positive

processor.add_inputs_to_inference_session(
    inference_session=inference_session,
    frame_idx=ann_frame_idx,
    obj_ids=obj_ids,
    input_points=input_points,
    input_labels=input_labels,
)

# Get masks for all objects on the first frame
outputs = model(
    inference_session=inference_session,
    frame_idx=ann_frame_idx,
)
video_res_masks = processor.post_process_masks(
    [outputs.pred_masks], original_sizes=[[inference_session.video_height, inference_session.video_width]], binarize=False
)[0]
print(f"Generated masks for {video_res_masks.shape[0]} objects")
Generated masks for 2 objects

# Propagate all objects through the video
video_segments = {}
for sam3_tracker_video_output in model.propagate_in_video_iterator(inference_session):
    video_res_masks = processor.post_process_masks(
        [sam3_tracker_video_output.pred_masks], original_sizes=[[inference_session.video_height, inference_session.video_width]], binarize=False
    )[0]
    video_segments[sam3_tracker_video_output.frame_idx] = {
        obj_id: video_res_masks[i]
        for i, obj_id in enumerate(inference_session.obj_ids)
    }

print(f"Tracked {len(inference_session.obj_ids)} objects through {len(video_segments)} frames")
Tracked 2 objects through 180 frames

Sam3TrackerVideoConfig

classe transformers.Sam3TrackerVideoConfig

< >

( 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 = Nonevision_config: dict | transformers.configuration_utils.PreTrainedConfig | None = Noneprompt_encoder_config: dict | transformers.configuration_utils.PreTrainedConfig | None = Nonemask_decoder_config: dict | transformers.configuration_utils.PreTrainedConfig | None = Noneinitializer_range: float = 0.02num_maskmem: int = 7sigmoid_scale_for_mem_enc: float = 20.0sigmoid_bias_for_mem_enc: float = -10.0enable_occlusion_spatial_embedding: bool = Truemultimask_output_in_sam: bool = Truemultimask_min_pt_num: int = 0multimask_max_pt_num: int = 1multimask_output_for_tracking: bool = Truemax_object_pointers_in_encoder: int = 16max_cond_frame_num: int = 4enable_temporal_pos_encoding_for_object_pointers: bool = Truememory_attention_hidden_size: int = 256memory_attention_num_layers: int = 4memory_attention_num_attention_heads: int = 1memory_attention_downsample_rate: int = 1memory_attention_feed_forward_hidden_size: int = 2048memory_attention_feed_forward_hidden_act: str = 'relu'memory_attention_dropout: float | int = 0.1memory_attention_rope_feat_sizes: list | None = Nonememory_attention_rope_dropout: float | int = 0.1memory_encoder_hidden_size: int = 256memory_encoder_output_channels: int = 64rope_parameters: dict | None = Nonemask_downsampler_embed_dim: int = 256mask_downsampler_kernel_size: int = 3mask_downsampler_stride: int = 2mask_downsampler_padding: int = 1mask_downsampler_total_stride: int = 16mask_downsampler_hidden_act: str = 'gelu'memory_fuser_num_layers: int = 2memory_fuser_embed_dim: int = 256memory_fuser_intermediate_dim: int = 1024memory_fuser_kernel_size: int = 7memory_fuser_padding: int = 3memory_fuser_layer_scale_init_value: float = 1e-06memory_fuser_hidden_act: str = 'gelu' )

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, Sam3TrackerVideoPromptEncoderConfig], opcional) — Dicionário de opções de configuração usado para inicializar Sam3TrackerVideoPromptEncoderConfig.
  • mask_decoder_config (Union[dict, Sam3TrackerVideoMaskDecoderConfig], opcional) — Dicionário de opções de configuração usado para inicializar Sam3TrackerVideoMaskDecoderConfig.
  • initializer_range (float, opcional, padrão 0.02) — Desvio padrão para a inicialização dos parâmetros.
  • num_maskmem (int, opcional, padrão 7) — O número de slots de memória para a memória de máscara.
  • sigmoid_scale_for_mem_enc (float, opcional, padrão 20.0) — Fator de escala para a função sigmoid no codificador de memória.
  • sigmoid_bias_for_mem_enc (float, opcional, padrão -10.0) — Viés para a função sigmoid no codificador de memória.
  • enable_occlusion_spatial_embedding (bool, opcional, padrão True) — Se deve habilitar o embedding espacial para oclusões.
  • multimask_output_in_sam (bool, opcional, padrão True) — Se deve gerar múltiplas máscaras a partir da cabeça do SAM.
  • multimask_min_pt_num (int, opcional, padrão 0) — O número mínimo de pontos para acionar a saída multimask.
  • multimask_max_pt_num (int, opcional, padrão 1) — O número máximo de pontos para acionar a saída multimask.
  • multimask_output_for_tracking (bool, opcional, padrão True) — Se deve usar a saída multimask para rastreamento.
  • max_object_pointers_in_encoder (int, opcional, padrão 16) — O número máximo de ponteiros de objetos no encoder.
  • max_cond_frame_num (int, opcional, padrão 4) — Número máximo de frames de condicionamento a serem usados na atenção de memória.
  • enable_temporal_pos_encoding_for_object_pointers (bool, opcional, padrão True) — Se deve habilitar a codificação posicional temporal para ponteiros de objetos.
  • memory_attention_hidden_size (int, opcional, padrão 256) — Dimensão dos estados ocultos da atenção de memória.
  • memory_attention_num_layers (int, opcional, padrão 4) — O número de camadas no módulo de atenção de memória.
  • memory_attention_num_attention_heads (int, opcional, padrão 1) — Número de cabeças de atenção para cada camada de atenção na memória de atenção.
  • memory_attention_downsample_rate (int, opcional, padrão 1) — A taxa de downsampling para as camadas de atenção.
  • memory_attention_feed_forward_hidden_size (int, opcional, padrão 2048) — A dimensão da rede feedforward no módulo de atenção de memória.
  • memory_attention_feed_forward_hidden_act (str, opcional, padrão "relu") — A função de ativação não linear na rede feedforward do módulo de atenção de memória.
  • memory_attention_dropout (float, opcional, padrão 0.1) — A taxa de dropout para o módulo de atenção de memória.
  • memory_attention_rope_feat_sizes (list[int], opcional, padrão [72, 72]) — Os tamanhos dos recursos para a codificação posicional Rope.
  • memory_attention_rope_dropout (float, opcional, padrão 0.1) — A taxa de dropout para a codificação posicional Rope.
  • memory_encoder_hidden_size (int, opcional, padrão 256) — Dimensão dos estados ocultos do codificador de memória.
  • memory_encoder_output_channels (int, opcional, padrão 64) — O número de canais de saída para o codificador de memória.
  • rope_parameters (dict, opcional) — Dicionário contendo os parâmetros de configuração para os embeddings RoPE. O dicionário deve conter um valor para rope_theta e, opcionalmente, parâmetros usados para escalonamento, caso você queira usar RoPE com max_position_embeddings maiores.
  • mask_downsampler_embed_dim (int, opcional, padrão 256) — A dimensão do embedding do downsampler de máscara.
  • mask_downsampler_kernel_size (int, opcional, padrão 3) — O tamanho do kernel para o redutor de resolução da máscara.
  • mask_downsampler_stride (int, opcional, padrão 2) — O stride para o downsampler de máscara.
  • mask_downsampler_padding (int, opcional, padrão 1) — O padding para o downsampler da máscara.
  • mask_downsampler_total_stride (int, opcional, padrão 16) — O stride total para o downsampler de máscara.
  • mask_downsampler_hidden_act (str, opcional, padrão "gelu") — A função de ativação não linear no redutor de máscara.
  • memory_fuser_num_layers (int, opcional, padrão 2) — O número de camadas no memory fuser.
  • memory_fuser_embed_dim (int, opcional, padrão 256) — A dimensão da camada de incorporação no memory fuser.
  • memory_fuser_intermediate_dim (int, opcional, padrão 1024) — A dimensão da camada intermediária no memory fuser.
  • memory_fuser_kernel_size (int, opcional, padrão 7) — O tamanho do kernel para o memory fuser.
  • memory_fuser_padding (int, opcional, padrão 3) — O padding para o memory fuser.
  • memory_fuser_layer_scale_init_value (float, opcional, padrão 1e-06) — O valor inicial para a escala da camada no memory fuser.
  • memory_fuser_hidden_act (str, opcional, padrão "gelu") — A função de ativação não linear no memory fuser.

Esta é a classe de configuração para armazenar a configuração de um Sam3TrackerVideoModel. Ela é usada para instanciar um modelo Sam3 Tracker Video 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 (
...     Sam3VisionConfig,
...     Sam3TrackerVideoPromptEncoderConfig,
...     Sam3TrackerVideoMaskDecoderConfig,
...     Sam3TrackerVideoModel,
... )

>>> # Initializing a Sam3TrackerVideoConfig with `"facebook/sam3"` style configuration
>>> configuration = Sam3TrackerVideoConfig()

>>> # Initializing a Sam3TrackerVideoModel (with random weights) from the `"facebook/sam3"` style configuration
>>> model = Sam3TrackerVideoModel(configuration)

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

>>> # We can also initialize a Sam3TrackerVideoConfig from a Sam3TrackerVideoVisionConfig, Sam3TrackerVideoPromptEncoderConfig, and Sam3TrackerVideoMaskDecoderConfig

>>> # Initializing SAM3 tracker video vision encoder, memory attention, and memory encoder configurations
>>> vision_config = Sam3TrackerVideoVisionConfig()
>>> prompt_encoder_config = Sam3TrackerVideoPromptEncoderConfig()
>>> mask_decoder_config = Sam3TrackerVideoMaskDecoderConfig()

>>> config = Sam3TrackerVideoConfig(vision_config, prompt_encoder_config, mask_decoder_config)

Sam3TrackerVideoMaskDecoderConfig

classe transformers.Sam3TrackerVideoMaskDecoderConfig

< >

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

Esta é a classe de configuração para armazenar a configuração de um Sam3TrackerVideoModel. Ela é usada para instanciar um modelo Sam3 Tracker Video 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.

Sam3TrackerVideoPromptEncoderConfig

classe transformers.Sam3TrackerVideoPromptEncoderConfig

< >

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

Esta é a classe de configuração para armazenar a configuração de um Sam3TrackerVideoModel. Ela é usada para instanciar um modelo Sam3 Tracker Video 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.

Sam3TrackerVideoProcessor

classe transformers.Sam3TrackerVideoProcessor

< >

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

Parâmetros

  • image_processor (Sam3ImageProcessor) — O processador de imagem é uma entrada obrigatória.
  • video_processor (video_processor_class) — O processador de vídeo é 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 Sam3TrackerVideoProcessor que encapsula um processador de imagem e um processador de vídeo em um único processador.

Sam3TrackerVideoProcessor oferece todas as funcionalidades de Sam3ImageProcessor e video_processor_class. Consulte ~Sam3ImageProcessor e ~video_processor_class para mais informações.

__call__

< >

( 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

< >

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

init_video_session

< >

( video: typing.Union[list['PIL.Image.Image'], numpy.ndarray, ForwardRef('torch.Tensor'), list[numpy.ndarray], list['torch.Tensor'], list[list['PIL.Image.Image']], list[list[numpy.ndarray]], list[list['torch.Tensor']], transformers.video_utils.URL, list[transformers.video_utils.URL], list[list[transformers.video_utils.URL]], transformers.video_utils.Path, list[transformers.video_utils.Path], list[list[transformers.video_utils.Path]], NoneType] = Noneinference_device: typing.Union[str, ForwardRef('torch.device')] = 'cpu'inference_state_device: typing.Union[str, ForwardRef('torch.device'), NoneType] = Noneprocessing_device: typing.Union[str, ForwardRef('torch.device'), NoneType] = Nonevideo_storage_device: typing.Union[str, ForwardRef('torch.device'), NoneType] = Nonemax_vision_features_cache_size: int = 1dtype: dtype = torch.float32 )

Parâmetros

  • video (VideoInput, opcional) — O vídeo a ser processado. Não é necessário fornecer durante o streaming.
  • inference_device (str ou torch.device, opcional, padrão “cpu”) — O dispositivo a ser usado para inferência.
  • inference_state_device (str ou torch.device, opcional) — O dispositivo em que o estado de inferência será armazenado.
  • processing_device (str ou torch.device, opcional) — O dispositivo a ser usado para o processamento de vídeo.
  • video_storage_device (str ou torch.device, opcional) — O dispositivo em que os quadros de vídeo processados serão armazenados.
  • max_vision_features_cache_size (int, opcional, padrão 1) — O número máximo de recursos visuais a serem armazenados em cache.
  • dtype (torch.dtype, opcional, padrão torch.float32) — O dtype do torch a ser usado para toda a sessão.

Inicializa uma sessão de vídeo para inferência. Se um vídeo for fornecido (inferência assíncrona), o vídeo será processado e armazenado no video_storage_device.

add_inputs_to_inference_session

< >

( inference_session: Sam3TrackerVideoInferenceSessionframe_idx: intobj_ids: list[int] | intinput_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] = Noneinput_masks: typing.Union[numpy.ndarray, torch.Tensor, list[numpy.ndarray], list[torch.Tensor], NoneType] = Noneoriginal_size: tuple[int, int] | None = Noneclear_old_inputs: bool = True )

Parâmetros

  • inference_session (Sam3TrackerVideoInferenceSession) — A sessão de inferência para o vídeo.
  • frame_idx (int) — O índice do quadro a ser processado.
  • obj_ids (list[int] ou int) — O(s) ID(s) do objeto a associar ao ponto ou à caixa. Podem ser quaisquer inteiros e podem ser reutilizados posteriormente para especificar um objeto.
  • 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.
  • input_masks (np.ndarray, torch.Tensor, list[np.ndarray] ou list[torch.Tensor], opcional) — A(s) máscara(s) a ser adicionada(s) ao quadro.
  • original_size (tuple[int, int], opcional) — O tamanho original do vídeo. Forneça ao transmitir em streaming.
  • clear_old_inputs (bool, opcional, padrão True) — Se deve limpar as entradas antigas do objeto.

Processe novos pontos, caixas ou máscaras para um quadro de vídeo e adicione-os à sessão de inferência.

Sam3TrackerVideoInferenceSession

classe transformers.Sam3TrackerVideoInferenceSession

< >

( video: typing.Optional[torch.Tensor] = Nonevideo_height: int | None = Nonevideo_width: int | None = Noneinference_device: typing.Union[torch.device, str] = 'cpu'inference_state_device: typing.Union[torch.device, str] = 'cpu'video_storage_device: typing.Union[torch.device, str] = 'cpu'dtype: typing.Union[torch.dtype, str] = 'float32'max_vision_features_cache_size: int = 1 )

Parâmetros

  • video (torch.Tensor, opcional) — O vídeo a ser processado. Não é necessário fornecer durante o streaming.
  • video_height (int, opcional) — A altura do vídeo.
  • video_width (int, opcional) — A largura do vídeo.
  • inference_device (torch.device, opcional, padrão "cpu") — O dispositivo a ser usado para inferência.
  • inference_state_device (torch.device, opcional, padrão "cpu") — O dispositivo em que o estado de inferência será armazenado.
  • video_storage_device (torch.device, opcional, padrão "cpu") — O dispositivo em que o vídeo será armazenado.
  • dtype (torch.dtype, opcional, padrão "float32") — O dtype a ser usado para o vídeo.
  • max_vision_features_cache_size (int, opcional, padrão 1) — O número máximo de recursos visuais a serem armazenados em cache.

Gerencia os parâmetros, o estado e o cache da sessão de inferência de vídeo.

add_mask_inputs

< >

( obj_idx: intframe_idx: intinputs: Tensor )

Adicione entradas de máscara com posicionamento automático de dispositivo.

add_new_frame

< >

( pixel_values: Tensorframe_idx: int | None = None )

Adicione um novo frame com posicionamento automático de dispositivo.

add_point_inputs

< >

( obj_idx: intframe_idx: intinputs: dict )

Adicione entradas de ponto com posicionamento automático de dispositivo.

get_frame

< >

( frame_idx: int )

Obter quadro do vídeo.

get_obj_num

< >

( )

Obtenha o número total de ids de objetos únicos recebidos até o momento nesta sessão.

get_output

< >

( obj_idx: intframe_idx: intoutput_key: stris_conditioning_frame: bool = True )

Parâmetros

  • obj_idx (int) — O índice do objeto.
  • frame_idx (int) — O índice do quadro.
  • output_key (str) — A chave da saída.
  • is_conditioning_frame (bool) — Indica se a saída é para um quadro de condicionamento.

Obtenha a saída com gerenciamento inteligente de dispositivos.

obj_id_to_idx

< >

( obj_id: int )

Mapeia o ID do objeto para o índice, criando uma nova entrada, se necessário.

obj_idx_to_id

< >

( obj_idx: int )

Mapeia o índice do objeto no lado do modelo para o id do objeto no lado do cliente.

remove_mask_inputs

< >

( obj_idx: intframe_idx: int )

Remova as entradas de máscara.

remove_point_inputs

< >

( obj_idx: intframe_idx: int )

Remova as entradas de ponto.

reset_inference_session

< >

( )

Redefinir os dados de rastreamento e o cache.

reset_tracking_data

< >

( )

Redefinir os dados de rastreamento, mas manter o cache.

store_output

< >

( obj_idx: intframe_idx: intoutput_key: str | None = Noneoutput_value: typing.Union[torch.Tensor, dict, NoneType] = Noneis_conditioning_frame: bool = True )

Parâmetros

  • obj_idx (int) — O índice do objeto.
  • frame_idx (int) — O índice do quadro.
  • output_key (Optional[str]) — A chave da saída. Se for None, a saída é armazenada como um dicionário.
  • output_value (Optional[Union[torch.Tensor, dict]]) — O valor da saída.
  • is_conditioning_frame (bool) — Indica se a saída é para um quadro de condicionamento.

Armazene a saída com gerenciamento inteligente de dispositivos. Se output_key for None, a saída é armazenada como um dicionário.

Sam3TrackerVideoModel

classe transformers.Sam3TrackerVideoModel

< >

( config: Sam3TrackerVideoConfigremove_vision_encoder: bool = False )

Parâmetros

  • config (Sam3TrackerVideoConfig) — 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.
  • remove_vision_encoder (bool, opcional, padrão False) — Se deve remover o codificador de visão. Se True, o codificador de visão será definido como None.

O modelo de rastreamento de vídeo Sam3 básico, que produz estados ocultos brutos sem nenhum cabeçalho específico no topo.

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

< >

( inference_session: Sam3TrackerVideoInferenceSessionframe_idx: int | None = Noneframe: typing.Optional[torch.Tensor] = Nonereverse: bool = Falserun_mem_encoder: bool = True**kwargs ) → Sam3TrackerVideoSegmentationOutput or tuple(torch.Tensor)

Parâmetros

  • inference_session (~models.sam3_tracker_video.modeling_sam3_tracker_video.Sam3TrackerVideoInferenceSession) — O objeto de sessão de inferência de vídeo.
  • frame_idx (int, opcional) — O índice do quadro em que a inferência será executada. Não é necessário fornecer ao inferir em um novo quadro transmitido.
  • frame (torch.Tensor, opcional) — O frame a ser processado. Forneça durante o streaming.
  • reverse (bool, opcional, padrão False) — Se deve propagar em sentido inverso.
  • run_mem_encoder (bool, opcional, padrão True) — Se deve executar o codificador de memória nas máscaras previstas. O codificador de memória é processado em lote para todos os objetos, visando eficiência.

Retorna

Sam3TrackerVideoSegmentationOutput ou tuple(torch.Tensor)

Um Sam3TrackerVideoSegmentationOutput 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 (Sam3TrackerVideoConfig) e das entradas.

Propague os objetos por meio de um quadro de vídeo transmitido.

  • object_ids (list[int], opcional) — Lista dos IDs de objetos rastreados no quadro atual.
  • pred_masks (torch.Tensor de forma (batch_size, num_masks, height, width)) — As máscaras previstas armazenadas na resolução do modelo.
  • object_score_logits (torch.Tensor de forma (batch_size,), opcional) — Logits para as pontuações dos objetos, indicando se os objetos estão presentes.
  • frame_idx (int, opcional) — O índice do quadro do vídeo.

propagate_in_video_iterator

< >

( inference_session: Sam3TrackerVideoInferenceSessionstart_frame_idx: int | None = Nonemax_frame_num_to_track: int | None = Nonereverse: bool = Falseshow_progress_bar: bool = False ) → Sam3TrackerVideoSegmentationOutput or tuple(torch.Tensor)

Parâmetros

  • inference_session (~models.sam3_tracker_video.modeling_sam3_tracker_video.Sam3TrackerVideoInferenceSession) — O objeto de sessão de inferência de vídeo.
  • start_frame_idx (int, opcional) — O índice do quadro inicial para a propagação. Precisa ser fornecido se forward ainda não tiver sido chamado em novas entradas. Se não for fornecido, o índice do quadro inicial será o quadro mais antigo com pontos de entrada.
  • max_frame_num_to_track (int, opcional) — O número máximo de quadros a serem rastreados.
  • reverse (bool, opcional, padrão False) — Se deve propagar em sentido inverso.
  • show_progress_bar (bool, opcional, padrão False) — Se deve exibir uma barra de progresso durante a propagação.

Retorna

Sam3TrackerVideoSegmentationOutput ou tuple(torch.Tensor)

Um Sam3TrackerVideoSegmentationOutput 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 (Sam3TrackerVideoConfig) e das entradas.

Propaga os objetos pelos quadros do vídeo. Usado ao inicializar uma sessão de inferência com um vídeo inteiro. Gera Sam3TrackerVideoSegmentationOutput para cada quadro.

  • object_ids (list[int], opcional) — Lista dos IDs de objetos rastreados no quadro atual.
  • pred_masks (torch.Tensor de forma (batch_size, num_masks, height, width)) — As máscaras previstas armazenadas na resolução do modelo.
  • object_score_logits (torch.Tensor de forma (batch_size,), opcional) — Logits para as pontuações dos objetos, indicando se os objetos estão presentes.
  • frame_idx (int, opcional) — O índice do quadro do vídeo.

get_image_features

< >

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

Parâmetros

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

Retorna

Sam3TrackerVideoVisionEncoderOutput ou tuple(torch.Tensor)

Uma Sam3TrackerVideoVisionEncoderOutput 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 (Sam3TrackerVideoConfig) 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.

Update on GitHub