Hugging Face's logo

Transformers documentation

SAM3 跟踪器视频

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

该模型于 2025-11-19 贡献至 Hugging Face Transformers。

SAM3 跟踪器视频

SDPA FlashAttention

概述

SAM3（Segment Anything Model 3）在 SAM 3: Segment Anything with Concepts 中提出。

Sam3TrackerVideo 对视频执行 可提示视觉分割（PVS）。PVS 接收交互式视觉提示（点、框、掩码）或文本输入，以在视频帧中跟踪每个提示对应的特定对象实例。

Sam3TrackerVideo 是 SAM2 Video 的更新版本，在保持相同 API 的同时，提供了更优的性能和功能。

该论文的摘要如下：

我们提出了 Segment Anything Model (SAM) 3，这是一个统一的模型，能够基于概念提示（concept prompts）在图像和视频中对目标进行检测、分割和跟踪。我们将概念提示定义为短名词短语（例如，“yellow school bus”）、图像示例（image exemplars），或两者的组合。可提示概念分割（Promptable Concept Segmentation, PCS）接收此类提示，并返回所有匹配目标实例的分割掩码和唯一标识。为了推动 PCS 的发展，我们构建了一个可扩展的数据引擎，生成了一个包含 400 万个唯一概念标签的高质量数据集，涵盖图像和视频，并包含困难负样本。我们的模型由一个图像级检测器和一个基于记忆的视频跟踪器组成，二者共享同一个骨干网络。通过引入存在性头（presence head）将识别与定位解耦，从而提升了检测精度。SAM 3 在图像和视频 PCS 任务上的准确率是现有系统的两倍，并提升了先前 SAM 在视觉分割任务上的能力。我们开源了 SAM 3，以及用于可提示概念分割的新基准 Segment Anything with Concepts (SA-Co)。

该模型由 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 函数的缩放因子。
  • sigmoid_bias_for_mem_enc (float, 可选，默认为 -10.0) — 记忆编码器中 sigmoid 函数的偏置。
  • enable_occlusion_spatial_embedding (bool，可选，默认为 True) — 是否启用遮挡的空间嵌入。
  • multimask_output_in_sam (bool，可选，默认为 True) — 是否从 SAM 头输出多个掩码。
  • multimask_min_pt_num (int，可选，默认为 0) — 触发多掩码输出的最小点数。
  • multimask_max_pt_num (int，可选，默认值为 1) — 触发多掩码输出的最大点数。
  • 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_downsample_rate (int，可选，默认为 1) — 注意力层的下采样率。
  • memory_attention_feed_forward_hidden_size (int, 可选，默认为 2048) — 记忆注意力模块中前馈网络的维度。
  • memory_attention_feed_forward_hidden_act (str，可选，默认为 "relu") — 记忆注意力模块中前馈网络的非线性激活函数。
  • memory_attention_dropout (float，可选，默认值为 0.1) — 内存注意力模块的 dropout 率。
  • memory_attention_rope_feat_sizes (list[int]，可选，默认为 [72, 72]) — Rope 位置编码的特征尺寸。
  • memory_attention_rope_dropout (float, 可选，默认值为 0.1) — Rope 位置编码的 dropout 率。
  • 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) — 掩码下采样器的嵌入维度。
  • mask_downsampler_kernel_size (int，可选，默认为 3) — 掩码下采样器的卷积核大小。
  • mask_downsampler_stride (int，可选，默认为 2) — 掩码下采样器的步长。
  • mask_downsampler_padding (int，可选，默认为 1) — 掩码下采样器的填充值。
  • mask_downsampler_total_stride (int，可选，默认为 16) — 掩码下采样器的总步幅。
  • mask_downsampler_hidden_act (str，可选，默认为 "gelu") — 掩码下采样器中的非线性激活函数。
  • memory_fuser_num_layers (int，可选，默认为 2) — 内存融合器中的层数。
  • memory_fuser_embed_dim (int，可选，默认为 256) — 记忆融合器中嵌入层的维度。
  • memory_fuser_intermediate_dim (int, 可选，默认为 1024) — memory fuser 中间层的维度。
  • memory_fuser_kernel_size (int，可选，默认为 7) — 内存融合器的卷积核大小。
  • memory_fuser_padding (int, 可选，默认为 3) — 内存融合器的填充值。
  • memory_fuser_layer_scale_init_value (float, 可选，默认为 1e-06) — memory fuser 中层缩放的初始值。
  • memory_fuser_hidden_act (str, 可选，默认为 "gelu") — 内存融合器中的非线性激活函数。

这是用于存储 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) — 双向 transformer 中 MLP 的维度。
  • num_hidden_layers (int，可选，默认为 2) — Transformer 解码器中的隐藏层数。
  • num_attention_heads (int，可选，默认为 8) — Transformer 解码器中每个注意力层的注意力头数量。
  • attention_downsample_rate (int，可选，默认为 2) — 注意力层的下采样率。
  • num_multimask_outputs (int，可选，默认为 3) — 多掩码输出的数量。
  • 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

class 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) — 每个 patch 的大小（分辨率）。
  • 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

class 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'：返回 PyTorch torch.Tensor 对象。
    • '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]]]) — 每张图片在调整至模型预期输入形状之前的原始尺寸，格式为 (height, width)。
  • 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 指定。

移除填充并将掩码上采样至原始图像尺寸。

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 或 torch.device，可选) — 用于存储处理后视频帧的设备。
  • max_vision_features_cache_size (int，可选，默认为 1) — 要缓存的视觉特征的最大数量。
  • dtype（torch.dtype，可选，默认为 torch.float32）— 用于整个会话的 torch dtype。

初始化用于推理的视频会话。 如果提供了视频（异步推理），该视频将被处理并存储在 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) — 要关联到点或框的对象 ID。 这些可以是任意整数，并且可以稍后重复使用以指定某个对象。
  • 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

class 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") — 用于视频的 dtype。
  • 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

< >

( )

获取当前会话中已接收到的唯一对象 ID 总数。

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) — 输出是否用于条件帧。

通过智能设备管理获取输出。

obj_id_to_idx

< >

( obj_id: int )

将对象 ID 映射到索引，如有必要则创建新条目。

obj_idx_to_id

< >

( obj_idx: int )

将模型端的对象索引映射到客户端的对象 ID。

remove_mask_inputs

< >

( obj_idx: intframe_idx: int )

移除 mask 输入。

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) — 输出是否用于条件帧。

使用智能设备管理来存储输出。 如果 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 Model，输出原始 hidden-states，顶部未添加任何特定的 head。

该模型继承自 PreTrainedModel。请查阅父类文档，了解该库为所有模型实现的通用方法（例如下载或保存、调整输入嵌入大小、剪枝头等）。

该模型也是 PyTorch torch.nn.Module 的子类。 请将其作为常规的 PyTorch Module 使用，有关通用用法和行为的所有事项，请参阅 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) — 是否对预测掩码运行内存编码器。为提高效率，内存编码器会对所有对象进行批处理。

返回值

Sam3TrackerVideoSegmentationOutput 或 tuple(torch.Tensor)

Sam3TrackerVideoSegmentationOutput 或 torch.Tensor 元组（当传入 return_dict=False 或 config.return_dict=False 时），其包含的元素取决于配置（Sam3TrackerVideoConfig）和输入。

通过流式视频帧传播对象。

  • object_ids (list[int]，可选) — 当前帧中正在跟踪的对象 ID 列表。
  • pred_masks（形状为 (batch_size, num_masks, height, width) 的 torch.Tensor）— 以模型分辨率存储的预测掩码。
  • object_score_logits (torch.Tensor，形状为 (batch_size,)，可选) — 对象分数的 logits，用于指示是否存在对象。
  • 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]，可选) — 当前帧中正在跟踪的对象 ID 列表。
  • pred_masks（形状为 (batch_size, num_masks, height, width) 的 torch.Tensor）— 以模型分辨率存储的预测掩码。
  • object_score_logits (torch.Tensor，形状为 (batch_size,)，可选) — 对象分数的 logits，用于指示是否存在对象。
  • 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（形状为 (batch_size, height, width, hidden_size) 的 torch.Tensor）— 模型最后一层输出的隐藏状态序列。

  • pooler_output (torch.Tensor，形状为 (batch_size, hidden_size)) — 序列中第一个 token（分类 token）的最后一层隐藏状态，经过用于辅助预训练任务的层进一步处理后得到。例如，对于 BERT 系列模型，这返回的是分类 token 经过线性层和 tanh 激活函数处理后的结果。线性层的权重在预训练期间通过下一句预测（分类）目标进行训练。

  • hidden_states (tuple(torch.Tensor)，可选，当传入 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 视频 TimeSformer→