Hugging Face's logo

Transformers documentation

SAM3 Tracker Video

You are viewing main version, which requires installation from source. If you'd like regular pip install, checkout the latest stable version (v5.22.2).
Hugging Face's logo
Join the Hugging Face community

and get access to the augmented documentation experience

to get started

Este modelo fue aportado a Hugging Face Transformers el 2025-11-19.

SAM3 Tracker Video

SDPA FlashAttention

Resumen

SAM3 (Segment Anything Model 3) se presentó en SAM 3: Segment Anything with Concepts.

Sam3TrackerVideo realiza Segmentación Visual con Prompts (PVS) en videos. PVS toma prompts visuales interactivos (puntos, cajas, máscaras) o entradas de texto para rastrear una instancia de objeto específica por prompt a lo largo de los fotogramas del video.

Sam3TrackerVideo es una versión actualizada de SAM2 Video que mantiene la misma API mientras ofrece un rendimiento y capacidades mejorados.

El resumen del artículo es el siguiente:

Presentamos Segment Anything Model (SAM) 3, un modelo unificado que detecta, segmenta y realiza seguimiento de objetos en imágenes y videos basándose en prompts de concepto, que definimos como frases nominales cortas (p. ej., “yellow school bus”), ejemplos de imagen o una combinación de ambos. La Segmentación de Conceptos con Prompts (PCS) toma dichos prompts y devuelve máscaras de segmentación e identidades únicas para todas las instancias de objetos coincidentes. Para avanzar en PCS, construimos un motor de datos escalable que produce un conjunto de datos de alta calidad con 4M de etiquetas de concepto únicas, incluyendo negativos difíciles, en imágenes y videos. Nuestro modelo consiste en un detector a nivel de imagen y un rastreador de video basado en memoria que comparten un único backbone. El reconocimiento y la localización se desacoplan mediante una presencia head, lo que mejora la precisión de la detección. SAM 3 duplica la precisión de los sistemas existentes tanto en PCS de imágenes como de videos, y mejora las capacidades anteriores de SAM en tareas de segmentación visual. Publicamos SAM 3 en código abierto junto con nuestro nuevo benchmark Segment Anything with Concepts (SA-Co) para la segmentación de conceptos con prompts.

Este modelo fue aportado por yonigozlan y ronghanghu.

Ejemplo de uso

Segmentación y seguimiento de video

Seguimiento básico de video

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

Seguimiento de video de múltiples objetos

Rastrear múltiples objetos simultáneamente a través de los fotogramas de un video:

# 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

Refinar la segmentación de video

Puede hacer clics adicionales en cualquier fotograma para refinar el seguimiento:

# 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

Inferencia de video en streaming

Para aplicaciones en tiempo real, Sam3TrackerVideo admite el procesamiento de fotogramas de vídeo a medida que llegan:

# 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}")

Procesamiento por lotes de video para múltiples objetos

Rastrea varios objetos simultáneamente en un video añadiéndolos todos a la 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

clase 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) — El objeto de configuración o el diccionario del backbone de visión.
  • prompt_encoder_config (Union[dict, Sam3TrackerVideoPromptEncoderConfig], opcional) — Diccionario de opciones de configuración utilizado para inicializar Sam3TrackerVideoPromptEncoderConfig.
  • mask_decoder_config (Union[dict, Sam3TrackerVideoMaskDecoderConfig], opcional) — Diccionario de opciones de configuración utilizado para inicializar Sam3TrackerVideoMaskDecoderConfig.
  • initializer_range (float, opcional, valor predeterminado 0.02) — Desviación estándar para la inicialización de parámetros.
  • num_maskmem (int, opcional, valor predeterminado 7) — El número de ranuras de memoria para la memoria de máscara.
  • sigmoid_scale_for_mem_enc (float, opcional, valor predeterminado 20.0) — Factor de escala para la función sigmoide en el codificador de memoria.
  • sigmoid_bias_for_mem_enc (float, opcional, valor predeterminado -10.0) — Sesgo para la función sigmoide en el codificador de memoria.
  • enable_occlusion_spatial_embedding (bool, opcional, valor predeterminado True) — Si se habilita el embedding espacial para las oclusiones.
  • multimask_output_in_sam (bool, opcional, valor predeterminado True) — Si se deben generar varias máscaras desde la cabeza de SAM.
  • multimask_min_pt_num (int, opcional, valor predeterminado 0) — El número mínimo de puntos para activar la salida multimask.
  • multimask_max_pt_num (int, opcional, valor predeterminado 1) — El número máximo de puntos para activar la salida multimask.
  • multimask_output_for_tracking (bool, opcional, valor predeterminado True) — Si se debe usar la salida multimask para el seguimiento.
  • max_object_pointers_in_encoder (int, opcional, valor predeterminado 16) — El número máximo de punteros de objetos en el codificador.
  • max_cond_frame_num (int, opcional, valor predeterminado 4) — Número máximo de fotogramas de condicionamiento a utilizar en la atención de memoria.
  • enable_temporal_pos_encoding_for_object_pointers (bool, opcional, valor predeterminado True) — Si se habilita la codificación posicional temporal para los punteros de objetos.
  • memory_attention_hidden_size (int, opcional, valor predeterminado 256) — Dimensionalidad de los estados ocultos de la atención de memoria.
  • memory_attention_num_layers (int, opcional, valor predeterminado 4) — El número de capas en el módulo de atención de memoria.
  • memory_attention_num_attention_heads (int, opcional, valor predeterminado 1) — Número de cabezas de atención para cada capa de atención en la atención de memoria.
  • memory_attention_downsample_rate (int, opcional, valor predeterminado 1) — La tasa de reducción de muestreo para las capas de atención.
  • memory_attention_feed_forward_hidden_size (int, opcional, valor predeterminado 2048) — La dimensión de la red feedforward en el módulo de atención de memoria.
  • memory_attention_feed_forward_hidden_act (str, opcional, valor predeterminado "relu") — La función de activación no lineal en la red feedforward del módulo de atención de memoria.
  • memory_attention_dropout (float, opcional, valor predeterminado 0.1) — La tasa de dropout para el módulo de atención de memoria.
  • memory_attention_rope_feat_sizes (list[int], opcional, valor predeterminado [72, 72]) — Los tamaños de las características para la codificación posicional Rope.
  • memory_attention_rope_dropout (float, opcional, valor predeterminado 0.1) — La tasa de dropout para la codificación posicional Rope.
  • memory_encoder_hidden_size (int, opcional, valor predeterminado 256) — Dimensionalidad de los estados ocultos del codificador de memoria.
  • memory_encoder_output_channels (int, opcional, valor predeterminado 64) — El número de canales de salida para el codificador de memoria.
  • rope_parameters (dict, opcional) — Diccionario que contiene los parámetros de configuración para las incrustaciones RoPE. El diccionario debe contener un valor para rope_theta y, opcionalmente, los parámetros utilizados para el escalado en caso de que desee usar RoPE con max_position_embeddings más largos.
  • mask_downsampler_embed_dim (int, opcional, valor predeterminado 256) — La dimensión de la incrustación del reductor de la máscara.
  • mask_downsampler_kernel_size (int, opcional, valor predeterminado 3) — El tamaño del kernel para el reductor de resolución de la máscara.
  • mask_downsampler_stride (int, opcional, valor predeterminado 2) — El paso (stride) del reductor de resolución de la máscara.
  • mask_downsampler_padding (int, opcional, valor predeterminado 1) — El relleno para el reductor de resolución de la máscara.
  • mask_downsampler_total_stride (int, opcional, valor predeterminado 16) — La longitud de paso total para el reductor de resolución de la máscara.
  • mask_downsampler_hidden_act (str, opcional, valor predeterminado "gelu") — La función de activación no lineal en el reductor de la máscara.
  • memory_fuser_num_layers (int, opcional, valor predeterminado 2) — El número de capas en el fusionador de memoria.
  • memory_fuser_embed_dim (int, opcional, valor predeterminado 256) — La dimensión de la capa de incrustación en el fusionador de memoria.
  • memory_fuser_intermediate_dim (int, opcional, valor predeterminado 1024) — La dimensión de la capa intermedia en el fusionador de memoria.
  • memory_fuser_kernel_size (int, opcional, valor predeterminado 7) — El tamaño del kernel para el fusionador de memoria.
  • memory_fuser_padding (int, opcional, valor predeterminado 3) — El relleno para el fusionador de memoria.
  • memory_fuser_layer_scale_init_value (float, opcional, valor predeterminado 1e-06) — El valor inicial de la escala de capa en el fusionador de memoria.
  • memory_fuser_hidden_act (str, opcional, valor predeterminado "gelu") — La función de activación no lineal en el fusionador de memoria.

Esta es la clase de configuración para almacenar la configuración de un Sam3TrackerVideoModel. Se utiliza para instanciar un modelo Sam3 Tracker Video según los argumentos especificados, definiendo la arquitectura del modelo. Instanciar una configuración con los valores predeterminados producirá una configuración similar a la de facebook/sam3

Los objetos de configuración heredan de PreTrainedConfig y se pueden usar para controlar las salidas del modelo. Lea la documentación de PreTrainedConfig para obtener más información.

Ejemplo:

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

clase 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, valor predeterminado 256) — Dimensión de las representaciones ocultas.
  • hidden_act (str, opcional, valor predeterminado gelu) — La función de activación no lineal (función o cadena) en el decodificador. Por ejemplo, "gelu", "relu", "silu", etc.
  • mlp_dim (int, opcional, valor predeterminado 2048) — La dimensión del MLP en el transformer de doble vía.
  • num_hidden_layers (int, opcional, valor predeterminado 2) — Número de capas ocultas en el decodificador del Transformer.
  • num_attention_heads (int, opcional, valor predeterminado 8) — Número de cabezas de atención para cada capa de atención en el decodificador Transformer.
  • attention_downsample_rate (int, opcional, valor predeterminado 2) — La tasa de reducción de muestreo para las capas de atención.
  • num_multimask_outputs (int, opcional, valor predeterminado 3) — El número de salidas multimask.
  • iou_head_depth (int, opcional, valor predeterminado 3) — La profundidad de la cabeza de IoU.
  • iou_head_hidden_dim (int, opcional, valor predeterminado 256) — La dimensión oculta de la cabeza de IoU.
  • dynamic_multimask_via_stability (bool, opcional, valor predeterminado True) — Si se debe usar la multimáscara dinámica a través de la estabilidad.
  • dynamic_multimask_stability_delta (float, opcional, valor predeterminado 0.05) — El delta de estabilidad para la multimáscara dinámica.
  • dynamic_multimask_stability_thresh (float, opcional, valor predeterminado 0.98) — Umbral de estabilidad para la multimáscara dinámica.

Esta es la clase de configuración para almacenar la configuración de un Sam3TrackerVideoModel. Se utiliza para instanciar un modelo Sam3 Tracker Video según los argumentos especificados, definiendo la arquitectura del modelo. Instanciar una configuración con los valores predeterminados producirá una configuración similar a la de facebook/sam3

Los objetos de configuración heredan de PreTrainedConfig y se pueden usar para controlar las salidas del modelo. Lea la documentación de PreTrainedConfig para obtener más información.

Sam3TrackerVideoPromptEncoderConfig

clase 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, valor predeterminado 256) — Dimensión de las representaciones ocultas.
  • image_size (Union[int, list[int], tuple[int, int]], opcional, valor predeterminado 1008) — El tamaño (resolución) de cada imagen.
  • patch_size (Union[int, list[int], tuple[int, int]], opcional, valor predeterminado 14) — El tamaño (resolución) de cada parche.
  • mask_input_channels (int, opcional, valor predeterminado 16) — El número de canales que se enviarán al módulo MaskDecoder.
  • num_point_embeddings (int, opcional, valor predeterminado 4) — El número de embeddings de puntos que se utilizarán.
  • hidden_act (str, opcional, valor predeterminado gelu) — La función de activación no lineal (función o cadena) en el decodificador. Por ejemplo, "gelu", "relu", "silu", etc.
  • layer_norm_eps (float, opcional, valor predeterminado 1e-06) — La epsilon utilizada por las capas de normalización de capa.
  • scale (float, opcional, valor predeterminado 1) — El factor de escala para el codificador de prompts.

Esta es la clase de configuración para almacenar la configuración de un Sam3TrackerVideoModel. Se utiliza para instanciar un modelo Sam3 Tracker Video según los argumentos especificados, definiendo la arquitectura del modelo. Instanciar una configuración con los valores predeterminados producirá una configuración similar a la de facebook/sam3

Los objetos de configuración heredan de PreTrainedConfig y se pueden usar para controlar las salidas del modelo. Lea la documentación de PreTrainedConfig para obtener más información.

Sam3TrackerVideoProcessor

clase transformers.Sam3TrackerVideoProcessor

< >

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

Parámetros

  • image_processor (Sam3ImageProcessor) — El procesador de imágenes es una entrada obligatoria.
  • video_processor (video_processor_class) — El procesador de video es una entrada obligatoria.
  • target_size (int, opcional) — El tamaño objetivo (en píxeles) para normalizar los puntos de entrada y las cajas delimitadoras. Si no se proporciona, se usa el tamaño configurado en el procesador de imágenes por defecto. Todas las coordenadas de entrada (puntos y cajas) se normalizan a este tamaño antes de pasarse al modelo. Esto garantiza una representación de coordenadas coherente, independientemente de las dimensiones originales de la imagen.
  • point_pad_value (int, opcional, valor predeterminado -10) — El valor utilizado para rellenar los puntos de entrada al agrupar secuencias de diferentes longitudes. Este valor se utiliza para marcar las posiciones rellenas y se conserva durante la normalización de coordenadas.

Construye un Sam3TrackerVideoProcessor que envuelve un procesador de imágenes y un procesador de video en un único procesador.

Sam3TrackerVideoProcessor ofrece todas las funcionalidades de Sam3ImageProcessor y video_processor_class. Consulte ~Sam3ImageProcessor y ~video_processor_class para obtener más información.

__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) — Imagen a preprocesar. Espera una imagen única o un lote de imágenes con valores de píxeles que van de 0 a 255. Si se pasan imágenes con valores de píxeles entre 0 y 1, establezca do_rescale=False.
  • segmentation_maps (ImageInput, opcional) — Los mapas de segmentación a procesar.
  • input_points (list[list[list[list[float]]]], torch.Tensor, opcional) — Los puntos que se van a añadir al marco.
  • input_labels (list[list[list[int]]], torch.Tensor, opcional) — Las etiquetas para los puntos.
  • input_boxes (list[list[list[float]]], torch.Tensor, opcional) — Las cajas delimitadoras que se van a añadir al fotograma.
  • original_sizes (list[list[float]], torch.Tensor, opcional) — Los tamaños originales de las imágenes.
  • return_tensors (Union[str, ~utils.generic.TensorType], opcional) — Si se establece, devolverá tensores de un marco de trabajo específico. Los valores aceptables son:
    • 'pt': Devuelve objetos torch.Tensor de PyTorch.
    • 'np': Devuelve objetos np.ndarray de NumPy.

Devuelve

Un BatchEncoding con los siguientes campos

  • pixel_values (torch.Tensor): La(s) imagen(es) procesada(s).
  • original_sizes (list[list[float]]): Los tamaños originales de las imágenes.
  • labels (torch.Tensor): Los mapas de segmentación procesados (si se proporcionan).
  • input_points (torch.Tensor): Los puntos procesados.
  • input_labels (torch.Tensor): Las etiquetas procesadas.
  • input_boxes (torch.Tensor): Las cajas delimitadoras procesadas.

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 por lotes del mask_decoder en formato (batch_size, num_channels, height, width).
  • original_sizes (Union[torch.Tensor, List[Tuple[int,int]]]) — Los tamaños originales de cada imagen antes de que se redimensionara a la forma de entrada esperada por el modelo, en formato (altura, ancho).
  • mask_threshold (float, opcional, valor predeterminado 0.0) — Umbral para las operaciones de binarización y posprocesamiento.
  • binarize (bool, opcional, valor predeterminado True) — Si se deben binarizar las máscaras.
  • max_hole_area (float, opcional, valor predeterminado 0.0) — El área máxima de un agujero que se rellenará.
  • max_sprinkle_area (float, opcional, valor predeterminado 0.0) — El área máxima de un sprinkle para rellenar.
  • apply_non_overlapping_constraints (bool, opcional, valor predeterminado False) — Si se aplican restricciones de no superposición a las máscaras.

Devuelve

(torch.Tensor)

Máscaras por lotes en el formato batch_size, num_channels, height, width, donde (height, width) está dado por original_size.

Eliminar el relleno y ampliar las máscaras al tamaño original de la imagen.

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) — El video a procesar. No es necesario proporcionarlo al transmitir en streaming.
  • inference_device (str o torch.device, opcional, por defecto “cpu”) — El dispositivo que se usará para la inferencia.
  • inference_state_device (str o torch.device, opcional) — El dispositivo en el que se almacenará el estado de inferencia.
  • processing_device (str o torch.device, opcional) — El dispositivo que se utilizará para el procesamiento de video.
  • video_storage_device (str o torch.device, opcional) — El dispositivo en el que se almacenarán los fotogramas de video procesados.
  • max_vision_features_cache_size (int, opcional, valor predeterminado 1) — El número máximo de características visuales que se pueden almacenar en caché.
  • dtype (torch.dtype, opcional, valor predeterminado torch.float32) — El dtype de torch que se usará para toda la sesión.

Inicializa una sesión de video para inferencia. Si se proporciona un video (inferencia asíncrona), el video se procesará y se almacenará en el 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) — La sesión de inferencia para el vídeo.
  • frame_idx (int) — El índice del fotograma a procesar.
  • obj_ids (list[int] o int) — El o los ID de objeto a asociar con los puntos o la caja. Pueden ser cualquier entero y pueden reutilizarse más adelante para especificar un objeto.
  • input_points (list[list[list[list[float]]]], torch.Tensor, opcional) — Los puntos que se van a añadir al marco.
  • input_labels (list[list[list[int]]], torch.Tensor, opcional) — Las etiquetas para los puntos.
  • input_boxes (list[list[list[float]]], torch.Tensor, opcional) — Las cajas delimitadoras que se van a añadir al fotograma.
  • input_masks (np.ndarray, torch.Tensor, list[np.ndarray] o list[torch.Tensor], opcional) — La(s) máscara(s) que se añadirán al fotograma.
  • original_size (tuple[int, int], opcional) — El tamaño original del video. Proporciónalo al transmitir en streaming.
  • clear_old_inputs (bool, opcional, valor predeterminado True) — Si se deben limpiar las entradas antiguas del objeto.

Procesar nuevos puntos, cajas o máscaras para un fotograma de video y añadirlos a la sesión de inferencia.

Sam3TrackerVideoInferenceSession

clase 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) — El video a procesar. No es necesario proporcionarlo al transmitir en streaming.
  • video_height (int, opcional) — La altura del video.
  • video_width (int, opcional) — El ancho del video.
  • inference_device (torch.device, opcional, por defecto "cpu") — El dispositivo que se utilizará para la inferencia.
  • inference_state_device (torch.device, opcional, valor predeterminado "cpu") — El dispositivo en el que se almacena el estado de inferencia.
  • video_storage_device (torch.device, opcional, valor predeterminado "cpu") — El dispositivo en el que se almacenará el video.
  • dtype (torch.dtype, opcional, valor predeterminado "float32") — El dtype a utilizar para el vídeo.
  • max_vision_features_cache_size (int, opcional, valor predeterminado 1) — El número máximo de características visuales que se pueden almacenar en caché.

Gestiona los parámetros, el estado y la caché de la sesión de inferencia de video.

add_mask_inputs

< >

( obj_idx: intframe_idx: intinputs: Tensor )

Agregue entradas de máscara con colocación automática de dispositivos.

add_new_frame

< >

( pixel_values: Tensorframe_idx: int | None = None )

Agregue un nuevo marco con colocación automática de dispositivos.

add_point_inputs

< >

( obj_idx: intframe_idx: intinputs: dict )

Agregue entradas de puntos con colocación automática de dispositivos.

get_frame

< >

( frame_idx: int )

Obtener un fotograma del video.

get_obj_num

< >

( )

Obtenga el número total de ids de objetos únicos recibidos hasta ahora en esta sesión.

get_output

< >

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

Parámetros

  • obj_idx (int) — El índice del objeto.
  • frame_idx (int) — El índice del fotograma.
  • output_key (str) — La clave de la salida.
  • is_conditioning_frame (bool) — Indica si la salida corresponde a un frame de condicionamiento.

Obtén la salida con una gestión inteligente de dispositivos.

obj_id_to_idx

< >

( obj_id: int )

Mapea el ID del objeto a un índice, creando una nueva entrada si es necesario.

obj_idx_to_id

< >

( obj_idx: int )

Mapea el índice de objeto del lado del modelo al id de objeto del lado del cliente.

remove_mask_inputs

< >

( obj_idx: intframe_idx: int )

Eliminar las entradas de máscara.

remove_point_inputs

< >

( obj_idx: intframe_idx: int )

Eliminar las entradas de puntos.

reset_inference_session

< >

( )

Restablecer los datos de seguimiento y la caché.

reset_tracking_data

< >

( )

Restablecer los datos de seguimiento pero conservar la caché.

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) — El índice del objeto.
  • frame_idx (int) — El índice del fotograma.
  • output_key (Optional[str]) — La clave de la salida. Si es None, la salida se almacena como un diccionario.
  • output_value (Optional[Union[torch.Tensor, dict]]) — El valor de la salida.
  • is_conditioning_frame (bool) — Indica si la salida corresponde a un frame de condicionamiento.

Almacena la salida con una gestión inteligente de dispositivos. Si output_key es None, la salida se almacena como un diccionario.

Sam3TrackerVideoModel

clase transformers.Sam3TrackerVideoModel

< >

( config: Sam3TrackerVideoConfigremove_vision_encoder: bool = False )

Parámetros

  • config (Sam3TrackerVideoConfig) — Clase de configuración del modelo con todos los parámetros del modelo. Inicializar con un archivo de configuración no carga los pesos asociados con el modelo, solo la configuración. Consulte el método from_pretrained() para cargar los pesos del modelo.
  • remove_vision_encoder (bool, opcional, valor predeterminado False) — Si se debe eliminar el codificador de visión. Si es True, el codificador de visión se establecerá en None.

El modelo de seguimiento de video Sam3 básico que genera estados ocultos sin ningún cabezal específico en la parte superior.

Este modelo hereda de PreTrainedModel. Consulta la documentación de la clase superior para los métodos genéricos que la biblioteca implementa para todos sus modelos (como la descarga o el guardado, el redimensionamiento de las incrustaciones de entrada, la poda de cabezas, etc.).

Este modelo también es una subclase de torch.nn.Module de PyTorch. Úsalo como un módulo de PyTorch regular y consulta la documentación de PyTorch para todo lo relacionado con el uso y el comportamiento generales.

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) — El objeto de sesión de inferencia de video.
  • frame_idx (int, opcional) — El índice del fotograma en el que se ejecutará la inferencia. No es necesario proporcionarlo al realizar la inferencia en un nuevo fotograma transmitido.
  • frame (torch.Tensor, opcional) — El fotograma a procesar. Proporciónalo al transmitir en streaming.
  • reverse (bool, opcional, por defecto False) — Si se debe propagar en reversa.
  • run_mem_encoder (bool, opcional, valor predeterminado True) — Si se ejecuta el codificador de memoria en las máscaras predichas. El codificador de memoria se procesa por lotes para todos los objetos para mejorar la eficiencia.

Devuelve

Sam3TrackerVideoSegmentationOutput o tuple(torch.Tensor)

Un Sam3TrackerVideoSegmentationOutput o una tupla de torch.Tensor (si se pasa return_dict=False o cuando config.return_dict=False) que comprende varios elementos según la configuración (Sam3TrackerVideoConfig) y las entradas.

Propagar los objetos a través de un fotograma de video transmitido.

  • object_ids (list[int], opcional) — Lista de IDs de objetos que se están rastreando en el cuadro actual.
  • pred_masks (torch.Tensor de forma (batch_size, num_masks, height, width)) — Las máscaras predichas almacenadas en la resolución del modelo.
  • object_score_logits (torch.Tensor de forma (batch_size,), opcional) — Logits para las puntuaciones de los objetos, que indican si están presentes.
  • frame_idx (int, opcional) — El índice del fotograma del video.

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) — El objeto de sesión de inferencia de video.
  • start_frame_idx (int, opcional) — El índice de cuadro inicial para la propagación. Debe proporcionarse si forward no se ha llamado aún con nuevas entradas. Si no se proporciona, el índice de cuadro inicial será el cuadro más antiguo con puntos de entrada.
  • max_frame_num_to_track (int, opcional) — El número máximo de fotogramas a seguir.
  • reverse (bool, opcional, por defecto False) — Si se debe propagar en reversa.
  • show_progress_bar (bool, opcional, valor predeterminado False) — Si se muestra una barra de progreso durante la propagación.

Devuelve

Sam3TrackerVideoSegmentationOutput o tuple(torch.Tensor)

Un Sam3TrackerVideoSegmentationOutput o una tupla de torch.Tensor (si se pasa return_dict=False o cuando config.return_dict=False) que comprende varios elementos según la configuración (Sam3TrackerVideoConfig) y las entradas.

Propaga los objetos a través de los fotogramas del video. Se utiliza al inicializar una sesión de inferencia con un video completo. Devuelve Sam3TrackerVideoSegmentationOutput para cada fotograma.

  • object_ids (list[int], opcional) — Lista de IDs de objetos que se están rastreando en el cuadro actual.
  • pred_masks (torch.Tensor de forma (batch_size, num_masks, height, width)) — Las máscaras predichas almacenadas en la resolución del modelo.
  • object_score_logits (torch.Tensor de forma (batch_size,), opcional) — Logits para las puntuaciones de los objetos, que indican si están presentes.
  • frame_idx (int, opcional) — El índice del fotograma del video.

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 píxeles de entrada con forma (batch_size, num_channels, height, width).

Devuelve

Sam3TrackerVideoVisionEncoderOutput o tuple(torch.Tensor)

Un Sam3TrackerVideoVisionEncoderOutput o una tupla de torch.Tensor (si se pasa return_dict=False o cuando config.return_dict=False) que comprende varios elementos según la configuración (Sam3TrackerVideoConfig) y las entradas.

  • last_hidden_state (torch.Tensor de forma (batch_size, height, width, hidden_size)) — Secuencia de estados ocultos en la salida de la última capa del modelo.

  • pooler_output (torch.Tensor de forma (batch_size, hidden_size)) — Estado oculto de la última capa del primer token de la secuencia (token de clasificación) después de un procesamiento adicional a través de las capas utilizadas para la tarea de preentrenamiento auxiliar. Por ejemplo, para la familia de modelos BERT, esto devuelve el token de clasificación después de procesarlo a través de una capa lineal y una función de activación tanh. Los pesos de la capa lineal se entrenan a partir del objetivo de predicción de la siguiente oración (clasificación) durante el preentrenamiento.

  • hidden_states (tuple(torch.Tensor), opcional, devuelto cuando se pasa output_hidden_states=True o cuando config.output_hidden_states=True) — Tupla de torch.Tensor (una para la salida de las incrustaciones, si el modelo tiene una capa de incrustaciones, + una para la salida de cada capa) de forma (batch_size, sequence_length, hidden_size).

    Estados ocultos del modelo en la salida de cada capa más las salidas opcionales de la incrustación inicial.

  • attentions (tuple(torch.Tensor), opcional, se devuelve cuando se pasa output_attentions=True o cuando config.output_attentions=True) — Tupla de torch.Tensor (una por cada capa) de forma (batch_size, num_heads, sequence_length, sequence_length).

    Pesos de atención tras el softmax de atención, utilizados para calcular la media ponderada en las cabezas de autoatención.

  • fpn_hidden_states (tuple(torch.Tensor)) — Tupla de torch.Tensor (uno para cada nivel de características, de alta a baja resolución) de forma (batch_size, hidden_size, height, width). Mapas de características del cuello de la Feature Pyramid Network.

  • fpn_position_encoding (tuple(torch.Tensor)) — Tupla de torch.Tensor (una para cada nivel de características, de alta a baja resolución) de forma (batch_size, hidden_size, height, width). Codificaciones posicionales correspondientes a fpn_hidden_states.

Update on GitHub

←SAM2 Video TimeSformer→