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

Эта модель была добавлена в Hugging Face Transformers 19.11.2025.

SAM3 Tracker Video

SDPA FlashAttention

Обзор

SAM3 (Segment Anything Model 3) был представлен в статье SAM 3: Segment Anything with Concepts.

Sam3TrackerVideo выполняет Promptable Visual Segmentation (PVS) для видео. PVS использует интерактивные визуальные подсказки (точки, рамки, маски) или текстовые входные данные для отслеживания конкретного экземпляра объекта по каждой подсказке в кадрах видео.

Sam3TrackerVideo — это обновленная версия SAM2 Video, которая сохраняет тот же API, но обеспечивает улучшенную производительность и расширенные возможности.

Аннотация из статьи следующая:

Мы представляем Segment Anything Model (SAM) 3 — унифицированную модель, которая обнаруживает, сегментирует и отслеживает объекты на изображениях и в видео на основе концептуальных промптов, которые мы определяем как короткие существительные (например, «жёлтый школьный автобус»), образцы изображений или комбинацию обоих. Promptable Concept Segmentation (PCS) принимает такие промпты и возвращает маски сегментации и уникальные идентификаторы для всех соответствующих экземпляров объектов. Для развития PCS мы создали масштабируемый движок данных, который формирует высококачественный датасет с 4 млн уникальных концептуальных меток, включая сложные негативные примеры, для изображений и видео. Наша модель состоит из детектора на уровне изображения и видео-трекера на основе памяти, которые используют общий бэкбон. Распознавание и локализация разделены с помощью presence head, что повышает точность обнаружения. SAM 3 удваивает точность существующих систем как в PCS для изображений, так и для видео, а также улучшает возможности предыдущих версий SAM в задачах визуальной сегментации. Мы открыли исходный код SAM 3 вместе с нашим новым бенчмарком Segment Anything with Concepts (SA-Co) для promptable concept segmentation.

Эта модель была предоставлена yonigozlan и ronghanghu.

Пример использования

Сегментация и отслеживание объектов на видео

Базовое отслеживание видео

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

Отслеживание нескольких объектов на видео

Одновременное отслеживание нескольких объектов в кадрах видео:

# 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

Уточнение сегментации видео

Вы можете добавлять дополнительные клики на любом кадре, чтобы уточнить отслеживание:

# 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

Потоковое видео-инференс

Для приложений реального времени Sam3TrackerVideo поддерживает обработку кадров видео по мере их поступления:

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

Пакетная обработка видео для нескольких объектов

Одновременно отслеживайте несколько объектов в видео, добавляя их все сразу:

# 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

класс 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' )

Параметры

  • vision_config (Union[dict, ~configuration_utils.PreTrainedConfig], необязательный) — Объект конфигурации или словарь конфигурации визуального бэкбона.
  • prompt_encoder_config (Union[dict, Sam3TrackerVideoPromptEncoderConfig], необязательный) — Словарь с параметрами конфигурации, используемыми для инициализации Sam3TrackerVideoPromptEncoderConfig.
  • mask_decoder_config (Union[dict, Sam3TrackerVideoMaskDecoderConfig], необязательный) — Словарь с параметрами конфигурации, используемыми для инициализации Sam3TrackerVideoMaskDecoderConfig.
  • initializer_range (float, необязательный, по умолчанию 0.02) — Стандартное отклонение для инициализации параметров.
  • num_maskmem (int, необязательный, по умолчанию 7) — Количество слотов памяти для маскирующей памяти.
  • sigmoid_scale_for_mem_enc (float, необязательный, по умолчанию 20.0) — Коэффициент масштабирования для сигмоидной функции в кодировщике памяти.
  • sigmoid_bias_for_mem_enc (float, необязательный, по умолчанию -10.0) — Смещение для сигмоидной функции в кодировщике памяти.
  • enable_occlusion_spatial_embedding (bool, необязательный, по умолчанию True) — Включает ли пространственное встраивание для окклюзий.
  • multimask_output_in_sam (bool, необязательный, по умолчанию True) — Определяет, следует ли выводить несколько масок из SAM-головки.
  • multimask_min_pt_num (int, необязательный, по умолчанию 0) — Минимальное количество точек для запуска вывода multimask.
  • multimask_max_pt_num (int, необязательный, по умолчанию 1) — Максимальное количество точек, при котором активируется вывод multimask.
  • multimask_output_for_tracking (bool, необязательный, по умолчанию True) — Использовать ли вывод нескольких масок для отслеживания.
  • max_object_pointers_in_encoder (int, необязательный, по умолчанию 16) — Максимальное количество указателей на объекты в кодировщике.
  • max_cond_frame_num (int, необязательный, по умолчанию 4) — Максимальное количество кадров для условного контекста, используемых в памяти внимания.
  • enable_temporal_pos_encoding_for_object_pointers (bool, необязательный, по умолчанию True) — Включает ли временное позиционное кодирование для указателей на объекты.
  • memory_attention_hidden_size (int, необязательный, по умолчанию 256) — Размерность скрытых состояний внимания памяти.
  • memory_attention_num_layers (int, необязательный, по умолчанию 4) — Количество слоев в модуле внимания к памяти.
  • memory_attention_num_attention_heads (int, необязательный, по умолчанию 1) — Количество головок внимания в каждом слое внимания в блоке memory attention.
  • memory_attention_downsample_rate (int, необязательный, по умолчанию 1) — Коэффициент понижающей дискретизации для слоев внимания.
  • memory_attention_feed_forward_hidden_size (int, необязательный, по умолчанию 2048) — Размерность полносвязной сети в модуле внимания памяти.
  • memory_attention_feed_forward_hidden_act (str, необязательный, по умолчанию "relu") — Нелинейная функция активации в feedforward-сети модуля memory attention.
  • memory_attention_dropout (float, необязательный, по умолчанию 0.1) — Коэффициент dropout для модуля внимания к памяти.
  • memory_attention_rope_feat_sizes (list[int], необязательный, по умолчанию [72, 72]) — Размеры признаков для позиционного кодирования Rope.
  • memory_attention_rope_dropout (float, необязательный, по умолчанию 0.1) — Коэффициент dropout для позиционного кодирования Rope.
  • memory_encoder_hidden_size (int, необязательный, по умолчанию 256) — Размерность скрытых состояний кодировщика памяти.
  • memory_encoder_output_channels (int, необязательный, по умолчанию 64) — Количество выходных каналов для кодировщика памяти.
  • rope_parameters (dict, необязательный) — Словарь, содержащий параметры конфигурации для эмбеддингов RoPE. В словаре должно быть указано значение для rope_theta и, при необходимости, параметры, используемые для масштабирования, если вы хотите использовать RoPE с более длинными max_position_embeddings.
  • mask_downsampler_embed_dim (int, необязательный, по умолчанию 256) — Размерность эмбеддинга downsampler маски.
  • mask_downsampler_kernel_size (int, необязательный, по умолчанию 3) — Размер ядра для downsampler маски.
  • mask_downsampler_stride (int, необязательный, по умолчанию 2) — Шаг для downsampler маски.
  • mask_downsampler_padding (int, необязательный, по умолчанию 1) — Размер отступов (padding) для downsampler маски.
  • mask_downsampler_total_stride (int, необязательный, по умолчанию 16) — Общий шаг для даунсемплера маски.
  • mask_downsampler_hidden_act (str, необязательный, по умолчанию "gelu") — Нелинейная функция активации в модуле downsampler для маски.
  • memory_fuser_num_layers (int, необязательный, по умолчанию 2) — Количество слоёв в модуле memory fuser.
  • memory_fuser_embed_dim (int, необязательный, по умолчанию 256) — Размерность слоя встраивания в модуле memory fuser.
  • memory_fuser_intermediate_dim (int, необязательный, по умолчанию 1024) — Размерность промежуточного слоя в memory fuser.
  • memory_fuser_kernel_size (int, необязательный, по умолчанию 7) — Размер ядра для модуля слияния памяти.
  • memory_fuser_padding (int, необязательный, по умолчанию 3) — Размер отступа (padding) для memory fuser.
  • memory_fuser_layer_scale_init_value (float, необязательный, по умолчанию 1e-06) — Начальное значение масштаба слоя в memory fuser.
  • memory_fuser_hidden_act (str, необязательный, по умолчанию "gelu") — Нелинейная функция активации в модуле memory fuser.

Это класс конфигурации для хранения настроек модели Sam3TrackerVideoModel. Он используется для создания модели Sam3 Tracker Video в соответствии с указанными аргументами, определяя архитектуру модели. Создание конфигурации с параметрами по умолчанию даст конфигурацию, аналогичную конфигурации facebook/sam3

Объекты конфигурации наследуются от PreTrainedConfig и могут использоваться для управления выводами модели. Подробнее читайте в документации PreTrainedConfig.

Пример:

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

класс 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 )

Параметры

  • hidden_size (int, необязательный, по умолчанию 256) — Размерность скрытых представлений.
  • hidden_act (str, необязательный, по умолчанию gelu) — Нелинейная функция активации (функция или строка) в декодере. Например, "gelu", "relu", "silu" и т. д.
  • mlp_dim (int, необязательный, по умолчанию 2048) — Размерность MLP в двухстороннем трансформере.
  • num_hidden_layers (int, необязательный, по умолчанию 2) — Количество скрытых слоев в декодере Transformer.
  • num_attention_heads (int, необязательный, по умолчанию 8) — Количество головок внимания в каждом слое внимания декодера Transformer.
  • attention_downsample_rate (int, необязательный, по умолчанию 2) — Коэффициент понижающей дискретизации для слоев внимания.
  • num_multimask_outputs (int, необязательный, по умолчанию 3) — Количество выходов multimask.
  • iou_head_depth (int, необязательный, по умолчанию 3) — Глубина IoU-головы.
  • iou_head_hidden_dim (int, необязательный, по умолчанию 256) — Скрытое измерение IoU-головы.
  • dynamic_multimask_via_stability (bool, необязательный, по умолчанию True) — Использовать ли динамическую мультимаску через стабильность.
  • dynamic_multimask_stability_delta (float, необязательный, по умолчанию 0.05) — Дельта стабильности для динамической мультимаски.
  • dynamic_multimask_stability_thresh (float, необязательный, по умолчанию 0.98) — Порог стабильности для динамической мультимаски.

Это класс конфигурации для хранения настроек модели Sam3TrackerVideoModel. Он используется для создания модели Sam3 Tracker Video в соответствии с указанными аргументами, определяя архитектуру модели. Создание конфигурации с параметрами по умолчанию даст конфигурацию, аналогичную конфигурации facebook/sam3

Объекты конфигурации наследуются от PreTrainedConfig и могут использоваться для управления выводами модели. Подробнее читайте в документации PreTrainedConfig.

Sam3TrackerVideoPromptEncoderConfig

класс 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 )

Параметры

  • hidden_size (int, необязательный, по умолчанию 256) — Размерность скрытых представлений.
  • image_size (Union[int, list[int], tuple[int, int]], необязательный, по умолчанию 1008) — Размер (разрешение) каждого изображения.
  • patch_size (Union[int, list[int], tuple[int, int]], необязательный, по умолчанию 14) — Размер (разрешение) каждого патча.
  • mask_input_channels (int, необязательный, по умолчанию 16) — Количество каналов, передаваемых в модуль MaskDecoder.
  • num_point_embeddings (int, необязательный, по умолчанию 4) — Количество используемых точечных эмбеддингов.
  • hidden_act (str, необязательный, по умолчанию gelu) — Нелинейная функция активации (функция или строка) в декодере. Например, "gelu", "relu", "silu" и т. д.
  • layer_norm_eps (float, необязательный, по умолчанию 1e-06) — Значение epsilon, используемое слоями нормализации.
  • scale (float, необязательный, по умолчанию 1) — Коэффициент масштабирования для кодировщика промпта.

Это класс конфигурации для хранения настроек модели Sam3TrackerVideoModel. Он используется для создания модели Sam3 Tracker Video в соответствии с указанными аргументами, определяя архитектуру модели. Создание конфигурации с параметрами по умолчанию даст конфигурацию, аналогичную конфигурации facebook/sam3

Объекты конфигурации наследуются от PreTrainedConfig и могут использоваться для управления выводами модели. Подробнее читайте в документации PreTrainedConfig.

Sam3TrackerVideoProcessor

класс transformers.Sam3TrackerVideoProcessor

< >

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

Параметры

  • image_processor (Sam3ImageProcessor) — Обработчик изображений является обязательным входным параметром.
  • video_processor (video_processor_class) — Обработчик видео является обязательным входным параметром.
  • target_size (int, необязательный) — Целевой размер (в пикселях) для нормализации входных точек и ограничивающих прямоугольников. Если не указан, по умолчанию используется конфигурация размера процессора изображений. Все входные координаты (точки и прямоугольники) нормализуются до этого размера перед передачей в модель. Это обеспечивает единообразное представление координат независимо от исходных размеров изображения.
  • point_pad_value (int, необязательный, по умолчанию -10) — Значение, используемое для дополнения входных точек при пакетной обработке последовательностей разной длины. Это значение используется для пометки дополненных позиций и сохраняется при нормализации координат.

Создаёт Sam3TrackerVideoProcessor, который объединяет процессор изображений и процессор видео в единый процессор.

Sam3TrackerVideoProcessor предоставляет все возможности Sam3ImageProcessor и video_processor_class. Подробности см. в ~Sam3ImageProcessor и ~video_processor_class.

__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

Параметры

  • images (Union[PIL.Image.Image, numpy.ndarray, torch.Tensor, list[PIL.Image.Image], list[numpy.ndarray], list[torch.Tensor]], необязательный) — Изображение для предобработки. Ожидается одно изображение или батч изображений со значениями пикселей в диапазоне от 0 до 255. Если передаются изображения со значениями пикселей в диапазоне от 0 до 1, установите do_rescale=False.
  • segmentation_maps (ImageInput, необязательный) — Сегментационные карты для обработки.
  • input_points (list[list[list[list[float]]]], torch.Tensor, необязательный) — Точки, которые нужно добавить в кадр.
  • input_labels (list[list[list[int]]], torch.Tensor, необязательный) — Метки для точек.
  • input_boxes (list[list[list[float]]], torch.Tensor, необязательный) — Ограничивающие рамки, которые нужно добавить к кадру.
  • original_sizes (list[list[float]], torch.Tensor, необязательный) — Исходные размеры изображений.
  • return_tensors (Union[str, ~utils.generic.TensorType], необязательный) — Если задано, возвращает тензоры конкретного фреймворка. Допустимые значения:
    • 'pt': возвращает объекты torch.Tensor PyTorch.
    • 'np': возвращает объекты NumPy np.ndarray.

Возвращает

BatchEncoding со следующими полями

  • pixel_values (torch.Tensor): Обработанное изображение или изображения.
  • original_sizes (list[list[float]]): исходные размеры изображений.
  • labels (torch.Tensor): Обработанные карты сегментации (если предоставлены).
  • input_points (torch.Tensor): Обработанные точки.
  • input_labels (torch.Tensor): Обработанные метки.
  • input_boxes (torch.Tensor): Обработанные ограничивающие рамки.

post_process_masks

< >

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

Параметры

  • masks (Union[List[torch.Tensor], List[np.ndarray]]) — Пакетные маски из mask_decoder в формате (batch_size, num_channels, height, width).
  • original_sizes (Union[torch.Tensor, List[Tuple[int,int]]]) — Исходные размеры каждого изображения до его масштабирования до ожидаемой входной формы модели, в формате (высота, ширина).
  • mask_threshold (float, необязательный, по умолчанию 0.0) — Порог для бинаризации и операций постобработки.
  • binarize (bool, необязательный, по умолчанию True) — Указывает, следует ли бинаризировать маски.
  • max_hole_area (float, необязательный, по умолчанию 0.0) — Максимальная площадь отверстия, подлежащего заполнению.
  • max_sprinkle_area (float, необязательный, по умолчанию 0.0) — Максимальная площадь sprinkle, подлежащая заполнению.
  • apply_non_overlapping_constraints (bool, необязательный, по умолчанию False) — Указывает, следует ли применять ограничения на отсутствие перекрытий к маскам.

Возвращает

(torch.Tensor)

Маски в формате batch_size, num_channels, height, width, где (height, width) определяется параметром original_size.

Удалите заполнение (padding) и масштабируйте маски до исходного размера изображения.

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 )

Параметры

  • video (VideoInput, необязательный) — Видео для обработки. Не требуется при потоковой передаче.
  • inference_device (str или torch.device, необязательный, по умолчанию “cpu”) — Устройство, используемое для инференса.
  • inference_state_device (str или torch.device, необязательный) — Устройство, на котором хранится состояние инференса.
  • processing_device (str или torch.device, необязательный) — Устройство, используемое для обработки видео.
  • video_storage_device (str or torch.device, необязательный) — Устройство, на котором будут храниться обработанные кадры видео.
  • max_vision_features_cache_size (int, необязательный, по умолчанию 1) — Максимальное количество кэшируемых визуальных признаков.
  • dtype (torch.dtype, необязательный, по умолчанию torch.float32) — dtype PyTorch, используемый для всей сессии.

Инициализирует видеосессию для инференса. Если видео предоставлено (асинхронный инференс), оно будет обработано и сохранено на 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 )

Параметры

  • inference_session (Sam3TrackerVideoInferenceSession) — Сессия инференса для видео.
  • frame_idx (int) — Индекс обрабатываемого кадра.
  • obj_ids (list[int] или int) — Идентификатор(ы) объекта, который(е) нужно связать с точками или рамкой. Это могут быть любые целые числа, которые можно использовать повторно для указания объекта.
  • input_points (list[list[list[list[float]]]], torch.Tensor, необязательный) — Точки, которые нужно добавить в кадр.
  • input_labels (list[list[list[int]]], torch.Tensor, необязательный) — Метки для точек.
  • input_boxes (list[list[list[float]]], torch.Tensor, необязательный) — Ограничивающие рамки, которые нужно добавить к кадру.
  • input_masks (np.ndarray, torch.Tensor, list[np.ndarray] или list[torch.Tensor], необязательный) — Маска(и), которую(ые) нужно добавить к кадру.
  • original_size (tuple[int, int], необязательный) — Исходный размер видео. Укажите при потоковой передаче.
  • clear_old_inputs (bool, необязательный, по умолчанию True) — Определяет, следует ли очищать старые входные данные объекта.

Обрабатывайте новые точки, рамки или маски для кадра видео и добавляйте их в сессию инференса.

Sam3TrackerVideoInferenceSession

класс 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 )

Параметры

  • video (torch.Tensor, необязательный) — Видео для обработки. Не требуется при потоковой передаче.
  • video_height (int, необязательный) — Высота видео.
  • video_width (int, необязательный) — Ширина видео.
  • inference_device (torch.device, необязательный, по умолчанию "cpu") — Устройство, используемое для инференса.
  • inference_state_device (torch.device, необязательный, по умолчанию "cpu") — Устройство, на котором хранится состояние инференса.
  • video_storage_device (torch.device, необязательный, по умолчанию "cpu") — Устройство, на котором будет храниться видео.
  • dtype (torch.dtype, необязательный, по умолчанию "float32") — Тип данных, используемый для видео.
  • max_vision_features_cache_size (int, необязательный, по умолчанию 1) — Максимальное количество кэшируемых визуальных признаков.

Управляет параметрами, состоянием и кэшем сессии инференса видео.

add_mask_inputs

< >

( obj_idx: intframe_idx: intinputs: Tensor )

Добавьте входные маски с автоматическим размещением на устройстве.

add_new_frame

< >

( pixel_values: Tensorframe_idx: int | None = None )

Добавить новый кадр с автоматическим размещением на устройстве.

add_point_inputs

< >

( obj_idx: intframe_idx: intinputs: dict )

Добавьте входные данные в виде точек с автоматическим размещением на устройстве.

get_frame

< >

( frame_idx: int )

Получить кадр из видео.

get_obj_num

< >

( )

Получите общее количество уникальных идентификаторов объектов, полученных на данный момент в этой сессии.

get_output

< >

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

Параметры

  • obj_idx (int) — Индекс объекта.
  • frame_idx (int) — Индекс кадра.
  • output_key (str) — Ключ вывода.
  • is_conditioning_frame (bool) — Указывает, является ли вывод кадром для conditioning.

Получите вывод с умным управлением устройствами.

obj_id_to_idx

< >

( obj_id: int )

Соответствие идентификатора объекта индексу, при необходимости создавая новую запись.

obj_idx_to_id

< >

( obj_idx: int )

Соответствие индекса объекта на стороне модели идентификатору объекта на стороне клиента.

remove_mask_inputs

< >

( obj_idx: intframe_idx: int )

Удалите входные маски.

remove_point_inputs

< >

( obj_idx: intframe_idx: int )

Удалите входные точки.

reset_inference_session

< >

( )

Сбросить данные отслеживания и кэш.

reset_tracking_data

< >

( )

Сбросить данные отслеживания, но сохранить кэш.

store_output

< >

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

Параметры

  • obj_idx (int) — Индекс объекта.
  • frame_idx (int) — Индекс кадра.
  • output_key (Optional[str]) — Ключ вывода. Если значение равно None, результат сохраняется в виде словаря.
  • output_value (Optional[Union[torch.Tensor, dict]]) — Значение вывода.
  • is_conditioning_frame (bool) — Указывает, является ли вывод кадром для conditioning.

Сохраняйте вывод с умным управлением устройствами. Если output_key равно None, вывод сохраняется в виде словаря.

Sam3TrackerVideoModel

класс transformers.Sam3TrackerVideoModel

< >

( config: Sam3TrackerVideoConfigremove_vision_encoder: bool = False )

Параметры

  • config (Sam3TrackerVideoConfig) — Класс конфигурации модели со всеми параметрами модели. Инициализация с файлом конфигурации не загружает веса, связанные с моделью, только конфигурацию. Используйте метод from_pretrained() для загрузки весов модели.
  • remove_vision_encoder (bool, необязательный, по умолчанию False) — Удалять ли визуальный энкодер. Если True, визуальный энкодер будет установлен в None.

Модель Sam3 Tracker Video, выводящая необработанные скрытые состояния без какого-либо специализированного слоя на выходе.

Эта модель наследуется от PreTrainedModel. См. документацию родительского класса для общих методов, которые библиотека реализует для всех своих моделей (например, загрузка или сохранение, изменение размера входных эмбеддингов, обрезка голов и т. д.)

Эта модель также является подклассом torch.nn.Module в PyTorch. Используйте её как обычный модуль PyTorch и обращайтесь к документации PyTorch по всем вопросам, связанным с общим использованием и поведением.

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)

Параметры

  • inference_session (~models.sam3_tracker_video.modeling_sam3_tracker_video.Sam3TrackerVideoInferenceSession) — Объект сессии видеоинференса.
  • frame_idx (int, необязательный) — Индекс кадра, для которого выполняется инференс. Не требуется при инференсе на новом потоковом кадре.
  • frame (torch.Tensor, необязательный) — Кадр для обработки. Указывается при потоковой обработке.
  • reverse (bool, необязательный, по умолчанию False) — Указывает, следует ли распространять в обратном направлении.
  • run_mem_encoder (bool, необязательный, по умолчанию True) — Указывает, следует ли запускать memory encoder на предсказанных масках. Для эффективности memory encoder обрабатывает все объекты в одном батче.

Возвращает

Sam3TrackerVideoSegmentationOutput или tuple(torch.Tensor)

Sam3TrackerVideoSegmentationOutput или кортеж из torch.Tensor (если передано return_dict=False или если config.return_dict=False), содержащий различные элементы в зависимости от конфигурации (Sam3TrackerVideoConfig) и входных данных.

Передайте объекты через кадр потокового видео.

  • object_ids (list[int], необязательный) — Список идентификаторов объектов, отслеживаемых в текущем кадре.
  • pred_masks (torch.Tensor формы (batch_size, num_masks, height, width)) — Предсказанные маски, сохранённые в разрешении модели.
  • object_score_logits (torch.Tensor формы (batch_size,), необязательный) — Логиты для оценок объектов, указывающие на наличие объектов.
  • frame_idx (int, необязательный) — Индекс кадра видео.

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)

Параметры

  • inference_session (~models.sam3_tracker_video.modeling_sam3_tracker_video.Sam3TrackerVideoInferenceSession) — Объект сессии видеоинференса.
  • start_frame_idx (int, необязательный) — Индекс начального кадра для распространения. Должен быть указан, если forward ещё не вызывался для новых входных данных. Если не указан, индекс начального кадра будет соответствовать самому раннему кадру, содержащему входные точки.
  • max_frame_num_to_track (int, необязательный) — Максимальное количество кадров для отслеживания.
  • reverse (bool, необязательный, по умолчанию False) — Указывает, следует ли распространять в обратном направлении.
  • show_progress_bar (bool, необязательный, по умолчанию False) — Определяет, следует ли отображать индикатор прогресса во время распространения.

Возвращает

Sam3TrackerVideoSegmentationOutput или tuple(torch.Tensor)

Sam3TrackerVideoSegmentationOutput или кортеж из torch.Tensor (если передано return_dict=False или если config.return_dict=False), содержащий различные элементы в зависимости от конфигурации (Sam3TrackerVideoConfig) и входных данных.

Передаёт объекты через кадры видео. Используется при инициализации сессии инференса с полным видео. Возвращает Sam3TrackerVideoSegmentationOutput для каждого кадра.

  • object_ids (list[int], необязательный) — Список идентификаторов объектов, отслеживаемых в текущем кадре.
  • pred_masks (torch.Tensor формы (batch_size, num_masks, height, width)) — Предсказанные маски, сохранённые в разрешении модели.
  • object_score_logits (torch.Tensor формы (batch_size,), необязательный) — Логиты для оценок объектов, указывающие на наличие объектов.
  • frame_idx (int, необязательный) — Индекс кадра видео.

get_image_features

< >

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

Параметры

  • pixel_values (torch.Tensor) — Входные значения пикселей формы (batch_size, num_channels, height, width).

Возвращает

Sam3TrackerVideoVisionEncoderOutput или tuple(torch.Tensor)

Sam3TrackerVideoVisionEncoderOutput или кортеж из torch.Tensor (если передано return_dict=False или если config.return_dict=False), содержащий различные элементы в зависимости от конфигурации (Sam3TrackerVideoConfig) и входных данных.

  • last_hidden_state (torch.Tensor формы (batch_size, height, width, hidden_size)) — Последовательность скрытых состояний на выходе последнего слоя модели.

  • pooler_output (torch.Tensor формы (batch_size, hidden_size)) — Скрытое состояние последнего слоя для первого токена последовательности (токен классификации) после дополнительной обработки слоями, используемыми для вспомогательной задачи предварительного обучения. Например, для моделей семейства BERT это возвращает токен классификации после обработки линейным слоем и функцией активации tanh. Веса линейного слоя обучаются по задаче предсказания следующего предложения (классификации) во время предварительного обучения.

  • hidden_states (tuple(torch.Tensor), optional, возвращается, если передано output_hidden_states=True или если config.output_hidden_states=True) — кортеж из torch.Tensor (один для вывода слоя встраиваний, если модель имеет слой встраиваний, + один для вывода каждого слоя) формы (batch_size, sequence_length, hidden_size).

    Скрытые состояния модели на выходе каждого слоя, а также необязательные выходные значения начального слоя встраивания.

  • attentions (tuple(torch.Tensor), необязательный, возвращается при передаче output_attentions=True или при config.output_attentions=True) — Кортеж torch.Tensor (по одному на каждый слой) формы (batch_size, num_heads, sequence_length, sequence_length).

    Веса внимания после softmax в механизме внимания, используемые для вычисления взвешенного среднего в головах само-внимания.

  • fpn_hidden_states (tuple(torch.Tensor)) — Кортеж torch.Tensor (по одному для каждого уровня признаков, от высокого разрешения к низкому) формы (batch_size, hidden_size, height, width). Карты признаков из шейки Feature Pyramid Network.

  • fpn_position_encoding (tuple(torch.Tensor)) — Кортеж torch.Tensor (по одному для каждого уровня признаков, от высокого разрешения к низкому) с формой (batch_size, hidden_size, height, width). Позиционные кодировки, соответствующие fpn_hidden_states.

Update on GitHub

←SAM2 Video TimeSformer→