Hugging Face's logo

Transformers documentation

SAM3 Rastreador de Vídeo

You are viewing main version, which requires installation from source. If you'd like regular pip install, checkout the latest stable version (v5.22.1).
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

←SAM2 Vídeo TimeSformer→