Hugging Face's logo

Transformers documentation

SAM3 Tracker Vidéo

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

Ce modèle a été contribué à Hugging Face Transformers le 2025-11-19.

SAM3 Tracker Vidéo

SDPA FlashAttention

Aperçu

SAM3 (Segment Anything Model 3) a été introduit dans SAM 3: Segment Anything with Concepts.

Sam3TrackerVideo effectue une segmentation visuelle promptable (PVS) sur des vidéos. La PVS utilise des prompts visuels interactifs (points, boîtes, masques) ou des entrées textuelles pour suivre une instance d'objet spécifique par prompt à travers les images de la vidéo.

Sam3TrackerVideo est une version mise à jour de SAM2 Video qui conserve la même API tout en offrant des performances et des capacités améliorées.

L'abstract de l'article est le suivant :

Nous présentons Segment Anything Model (SAM) 3, un modèle unifié qui détecte, segmente et suit des objets dans des images et des vidéos à partir de prompts de concepts, que nous définissons comme des phrases nominales courtes (par exemple, « yellow school bus »), des exemplaires d’images, ou une combinaison des deux. La segmentation de concepts promptable (PCS) prend de tels prompts en entrée et renvoie des masques de segmentation et des identités uniques pour toutes les instances d’objets correspondantes. Pour faire progresser la PCS, nous avons construit un moteur de données scalable qui produit un jeu de données de haute qualité avec 4M de libellés de concepts uniques, incluant des négatifs difficiles, sur des images et des vidéos. Notre modèle se compose d’un détecteur au niveau de l’image et d’un suiveur vidéo basé sur la mémoire qui partagent un seul backbone. La reconnaissance et la localisation sont découplées par une tête de présence, ce qui améliore la précision de la détection. SAM 3 double la précision des systèmes existants en PCS sur images et vidéos, et améliore les capacités précédentes de SAM sur les tâches de segmentation visuelle. Nous open source SAM 3 ainsi que notre nouveau benchmark Segment Anything with Concepts (SA-Co) pour la segmentation de concepts promptable.

Ce modèle a été contribué par yonigozlan et ronghanghu.

Exemple d'utilisation

Segmentation et suivi vidéo

Suivi vidéo de base

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

Suivi vidéo multi-objets

Suivre plusieurs objets simultanément à travers les images vidéo :

# 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

Affiner la segmentation vidéo

Vous pouvez ajouter des clics supplémentaires sur n'importe quel plan pour affiner le suivi :

# 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

Inférence vidéo en streaming

Pour les applications en temps réel, Sam3TrackerVideo prend en charge le traitement des images vidéo à mesure qu'elles arrivent :

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

Traitement par lots de vidéos pour plusieurs objets

Suivre plusieurs objets simultanément dans une vidéo en les ajoutant tous d'un coup :

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

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

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

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

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

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

Sam3TrackerVideoConfig

classe transformers.Sam3TrackerVideoConfig

< >

( transformers_version: str | None = Nonearchitectures: list[str] | None = Noneoutput_hidden_states: bool | None = Falsereturn_dict: bool | None = Truedtype: str | torch.dtype | None = Nonechunk_size_feed_forward: int = 0is_encoder_decoder: bool = Falseid2label: dict[int, str] | dict[str, str] | None = Nonelabel2id: dict[str, int] | dict[str, str] | None = Noneproblem_type: Literal['regression', 'single_label_classification', 'multi_label_classification'] | None = Nonevision_config: dict | transformers.configuration_utils.PreTrainedConfig | None = Noneprompt_encoder_config: dict | transformers.configuration_utils.PreTrainedConfig | None = Nonemask_decoder_config: dict | transformers.configuration_utils.PreTrainedConfig | None = Noneinitializer_range: float = 0.02num_maskmem: int = 7sigmoid_scale_for_mem_enc: float = 20.0sigmoid_bias_for_mem_enc: float = -10.0enable_occlusion_spatial_embedding: bool = Truemultimask_output_in_sam: bool = Truemultimask_min_pt_num: int = 0multimask_max_pt_num: int = 1multimask_output_for_tracking: bool = Truemax_object_pointers_in_encoder: int = 16max_cond_frame_num: int = 4enable_temporal_pos_encoding_for_object_pointers: bool = Truememory_attention_hidden_size: int = 256memory_attention_num_layers: int = 4memory_attention_num_attention_heads: int = 1memory_attention_downsample_rate: int = 1memory_attention_feed_forward_hidden_size: int = 2048memory_attention_feed_forward_hidden_act: str = 'relu'memory_attention_dropout: float | int = 0.1memory_attention_rope_feat_sizes: list | None = Nonememory_attention_rope_dropout: float | int = 0.1memory_encoder_hidden_size: int = 256memory_encoder_output_channels: int = 64rope_parameters: dict | None = Nonemask_downsampler_embed_dim: int = 256mask_downsampler_kernel_size: int = 3mask_downsampler_stride: int = 2mask_downsampler_padding: int = 1mask_downsampler_total_stride: int = 16mask_downsampler_hidden_act: str = 'gelu'memory_fuser_num_layers: int = 2memory_fuser_embed_dim: int = 256memory_fuser_intermediate_dim: int = 1024memory_fuser_kernel_size: int = 7memory_fuser_padding: int = 3memory_fuser_layer_scale_init_value: float = 1e-06memory_fuser_hidden_act: str = 'gelu' )

Paramètres

  • vision_config (Union[dict, ~configuration_utils.PreTrainedConfig], facultatif) — L'objet de configuration ou le dictionnaire du backbone visuel.
  • prompt_encoder_config (Union[dict, Sam3TrackerVideoPromptEncoderConfig], facultatif) — Dictionnaire des options de configuration utilisées pour initialiser Sam3TrackerVideoPromptEncoderConfig.
  • mask_decoder_config (Union[dict, Sam3TrackerVideoMaskDecoderConfig], facultatif) — Dictionnaire des options de configuration utilisées pour initialiser Sam3TrackerVideoMaskDecoderConfig.
  • initializer_range (float, facultatif, valeur par défaut 0.02) — Écart type pour l'initialisation des paramètres.
  • num_maskmem (int, facultatif, valeur par défaut : 7) — Le nombre de slots mémoire pour la mémoire de masque.
  • sigmoid_scale_for_mem_enc (float, facultatif, valeur par défaut 20.0) — Facteur d'échelle de la fonction sigmoïde dans l'encodeur mémoire.
  • sigmoid_bias_for_mem_enc (float, facultatif, valeur par défaut -10.0) — Biais de la fonction sigmoïde dans l'encodeur mémoire.
  • enable_occlusion_spatial_embedding (bool, facultatif, valeur par défaut True) — Indique s'il faut activer l'incorporation spatiale pour les occlusions.
  • multimask_output_in_sam (bool, facultatif, par défaut True) — Indique s'il faut générer plusieurs masques à partir de la tête SAM.
  • multimask_min_pt_num (int, facultatif, valeur par défaut 0) — Nombre minimal de points pour déclencher la sortie multimask.
  • multimask_max_pt_num (int, facultatif, valeur par défaut 1) — Le nombre maximal de points pour déclencher la sortie multimask.
  • multimask_output_for_tracking (bool, facultatif, par défaut True) — Indique s'il faut utiliser la sortie multimask pour le suivi.
  • max_object_pointers_in_encoder (int, facultatif, valeur par défaut : 16) — Le nombre maximal de pointeurs d'objets dans l'encodeur.
  • max_cond_frame_num (int, facultatif, valeur par défaut : 4) — Nombre maximal de cadres de conditionnement à utiliser dans l'attention mémoire.
  • enable_temporal_pos_encoding_for_object_pointers (bool, facultatif, valeur par défaut True) — Indique s'il faut activer l'encodage positionnel temporel pour les pointeurs d'objets.
  • memory_attention_hidden_size (int, facultatif, valeur par défaut 256) — Dimension des états cachés de l'attention mémoire.
  • memory_attention_num_layers (int, facultatif, valeur par défaut : 4) — Le nombre de couches du module d'attention mémoire.
  • memory_attention_num_attention_heads (int, facultatif, valeur par défaut : 1) — Nombre de têtes d'attention pour chaque couche d'attention dans l'attention mémoire.
  • memory_attention_downsample_rate (int, facultatif, valeur par défaut 1) — Le taux de sous-échantillonnage pour les couches d'attention.
  • memory_attention_feed_forward_hidden_size (int, facultatif, valeur par défaut : 2048) — La dimension du réseau feedforward dans le module d'attention mémoire.
  • memory_attention_feed_forward_hidden_act (str, facultatif, par défaut "relu") — Fonction d'activation non linéaire du réseau feedforward dans le module d'attention mémoire.
  • memory_attention_dropout (float, facultatif, valeur par défaut 0.1) — Taux de dropout pour le module d'attention mémoire.
  • memory_attention_rope_feat_sizes (list[int], facultatif, valeur par défaut [72, 72]) — Les tailles de caractéristiques pour l'encodage positionnel Rope.
  • memory_attention_rope_dropout (float, facultatif, valeur par défaut 0.1) — Taux de dropout pour l'encodage positionnel Rope.
  • memory_encoder_hidden_size (int, facultatif, valeur par défaut 256) — Dimension des états cachés de l'encodeur mémoire.
  • memory_encoder_output_channels (int, facultatif, valeur par défaut 64) — Le nombre de canaux de sortie pour l'encodeur mémoire.
  • rope_parameters (dict, facultatif) — Dictionnaire contenant les paramètres de configuration des embeddings RoPE. Le dictionnaire doit contenir une valeur pour rope_theta et, le cas échéant, les paramètres utilisés pour le mise à l’échelle si vous souhaitez utiliser RoPE avec des max_position_embeddings plus longs.
  • mask_downsampler_embed_dim (int, facultatif, valeur par défaut 256) — La dimension de l’embedding du sous-échantillonneur de masque.
  • mask_downsampler_kernel_size (int, facultatif, valeur par défaut 3) — Taille du noyau pour le réducteur de masque.
  • mask_downsampler_stride (int, facultatif, valeur par défaut 2) — Le pas (stride) du sous-échantillonneur de masque.
  • mask_downsampler_padding (int, facultatif, valeur par défaut 1) — Le padding pour le réducteur de masque.
  • mask_downsampler_total_stride (int, facultatif, valeur par défaut 16) — Le pas total pour le réducteur de masque.
  • mask_downsampler_hidden_act (str, facultatif, par défaut "gelu") — La fonction d'activation non linéaire dans le sous-échantillonneur de masque.
  • memory_fuser_num_layers (int, facultatif, valeur par défaut : 2) — Le nombre de couches dans le fuser mémoire.
  • memory_fuser_embed_dim (int, facultatif, valeur par défaut : 256) — La dimension de la couche d'embedding dans le fuser de mémoire.
  • memory_fuser_intermediate_dim (int, facultatif, valeur par défaut : 1024) — La dimension de la couche intermédiaire du fuser de mémoire.
  • memory_fuser_kernel_size (int, facultatif, valeur par défaut : 7) — Taille du noyau pour le fuser mémoire.
  • memory_fuser_padding (int, facultatif, valeur par défaut : 3) — Le padding pour le memory fuser.
  • memory_fuser_layer_scale_init_value (float, facultatif, valeur par défaut 1e-06) — La valeur initiale de l'échelle de couche dans le fuser mémoire.
  • memory_fuser_hidden_act (str, facultatif, par défaut "gelu") — La fonction d'activation non linéaire dans le fuser mémoire.

Il s'agit de la classe de configuration permettant de stocker la configuration d'un Sam3TrackerVideoModel. Elle est utilisée pour instancier un modèle Sam3 Tracker Video en fonction des arguments spécifiés, en définissant l'architecture du modèle. L'instanciation d'une configuration avec les valeurs par défaut produira une configuration similaire à celle de facebook/sam3

Les objets de configuration héritent de PreTrainedConfig et peuvent être utilisés pour contrôler les sorties du modèle. Consultez la documentation de PreTrainedConfig pour plus d’informations.

Exemple :

>>> from transformers import (
...     Sam3VisionConfig,
...     Sam3TrackerVideoPromptEncoderConfig,
...     Sam3TrackerVideoMaskDecoderConfig,
...     Sam3TrackerVideoModel,
... )

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

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

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

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

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

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

Sam3TrackerVideoMaskDecoderConfig

classe transformers.Sam3TrackerVideoMaskDecoderConfig

< >

( transformers_version: str | None = Nonearchitectures: list[str] | None = Noneoutput_hidden_states: bool | None = Falsereturn_dict: bool | None = Truedtype: str | torch.dtype | None = Nonechunk_size_feed_forward: int = 0is_encoder_decoder: bool = Falseid2label: dict[int, str] | dict[str, str] | None = Nonelabel2id: dict[str, int] | dict[str, str] | None = Noneproblem_type: Literal['regression', 'single_label_classification', 'multi_label_classification'] | None = Nonehidden_size: int = 256hidden_act: str = 'gelu'mlp_dim: int = 2048num_hidden_layers: int = 2num_attention_heads: int = 8attention_downsample_rate: int = 2num_multimask_outputs: int = 3iou_head_depth: int = 3iou_head_hidden_dim: int = 256dynamic_multimask_via_stability: bool = Truedynamic_multimask_stability_delta: float = 0.05dynamic_multimask_stability_thresh: float = 0.98 )

Paramètres

  • hidden_size (int, facultatif, par défaut 256) — Dimension des représentations cachées.
  • hidden_act (str, facultatif, par défaut gelu) — La fonction d'activation non linéaire (fonction ou chaîne de caractères) du décodeur. Par exemple, "gelu", "relu", "silu", etc.
  • mlp_dim (int, facultatif, valeur par défaut 2048) — La dimension du MLP dans le transformateur bidirectionnel.
  • num_hidden_layers (int, facultatif, par défaut 2) — Nombre de couches cachées dans le décodeur Transformer.
  • num_attention_heads (int, facultatif, valeur par défaut 8) — Nombre de têtes d'attention pour chaque couche d'attention du décodeur Transformer.
  • attention_downsample_rate (int, facultatif, valeur par défaut 2) — Le taux de sous-échantillonnage pour les couches d'attention.
  • num_multimask_outputs (int, facultatif, valeur par défaut 3) — Le nombre de sorties multimask.
  • iou_head_depth (int, facultatif, valeur par défaut 3) — La profondeur de la tête IoU.
  • iou_head_hidden_dim (int, facultatif, valeur par défaut 256) — La dimension cachée de la tête IoU.
  • dynamic_multimask_via_stability (bool, facultatif, valeur par défaut True) — Indique s'il faut utiliser le multimask dynamique via la stabilité.
  • dynamic_multimask_stability_delta (float, facultatif, valeur par défaut 0.05) — La stabilité delta pour le multimask dynamique.
  • dynamic_multimask_stability_thresh (float, facultatif, valeur par défaut 0.98) — Seuil de stabilité pour le multimask dynamique.

Il s'agit de la classe de configuration permettant de stocker la configuration d'un Sam3TrackerVideoModel. Elle est utilisée pour instancier un modèle Sam3 Tracker Video en fonction des arguments spécifiés, en définissant l'architecture du modèle. L'instanciation d'une configuration avec les valeurs par défaut produira une configuration similaire à celle de facebook/sam3

Les objets de configuration héritent de PreTrainedConfig et peuvent être utilisés pour contrôler les sorties du modèle. Consultez la documentation de PreTrainedConfig pour plus d’informations.

Sam3TrackerVideoPromptEncoderConfig

classe transformers.Sam3TrackerVideoPromptEncoderConfig

< >

( transformers_version: str | None = Nonearchitectures: list[str] | None = Noneoutput_hidden_states: bool | None = Falsereturn_dict: bool | None = Truedtype: str | torch.dtype | None = Nonechunk_size_feed_forward: int = 0is_encoder_decoder: bool = Falseid2label: dict[int, str] | dict[str, str] | None = Nonelabel2id: dict[str, int] | dict[str, str] | None = Noneproblem_type: Literal['regression', 'single_label_classification', 'multi_label_classification'] | None = Nonehidden_size: int = 256image_size: int | list[int] | tuple[int, int] = 1008patch_size: int | list[int] | tuple[int, int] = 14mask_input_channels: int = 16num_point_embeddings: int = 4hidden_act: str = 'gelu'layer_norm_eps: float = 1e-06scale: int = 1 )

Paramètres

  • hidden_size (int, facultatif, par défaut 256) — Dimension des représentations cachées.
  • image_size (Union[int, list[int], tuple[int, int]], facultatif, par défaut 1008) — La taille (résolution) de chaque image.
  • patch_size (Union[int, list[int], tuple[int, int]], facultatif, par défaut 14) — La taille (résolution) de chaque patch.
  • mask_input_channels (int, facultatif, valeur par défaut 16) — Le nombre de canaux à transmettre au module MaskDecoder.
  • num_point_embeddings (int, facultatif, par défaut 4) — Le nombre d'embeddings de points à utiliser.
  • hidden_act (str, facultatif, par défaut gelu) — La fonction d'activation non linéaire (fonction ou chaîne de caractères) du décodeur. Par exemple, "gelu", "relu", "silu", etc.
  • layer_norm_eps (float, facultatif, valeur par défaut 1e-06) — L'épsilon utilisé par les couches de normalisation de couche.
  • scale (float, facultatif, valeur par défaut 1) — Le facteur d'échelle pour l'encodeur de prompt.

Il s'agit de la classe de configuration permettant de stocker la configuration d'un Sam3TrackerVideoModel. Elle est utilisée pour instancier un modèle Sam3 Tracker Video en fonction des arguments spécifiés, en définissant l'architecture du modèle. L'instanciation d'une configuration avec les valeurs par défaut produira une configuration similaire à celle de facebook/sam3

Les objets de configuration héritent de PreTrainedConfig et peuvent être utilisés pour contrôler les sorties du modèle. Consultez la documentation de PreTrainedConfig pour plus d’informations.

Sam3TrackerVideoProcessor

classe transformers.Sam3TrackerVideoProcessor

< >

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

Paramètres

  • image_processor (Sam3ImageProcessor) — Le processeur d’images est une entrée obligatoire.
  • video_processor (video_processor_class) — Le processeur vidéo est une entrée obligatoire.
  • target_size (int, facultatif) — Taille cible (en pixels) pour la normalisation des points et des boîtes englobantes d’entrée. Si non fournie, la valeur par défaut est la configuration de taille du processeur d’images. Toutes les coordonnées d’entrée (points et boîtes) sont normalisées à cette taille avant d’être transmises au modèle. Cela garantit une représentation cohérente des coordonnées, indépendamment des dimensions d’origine de l’image.
  • point_pad_value (int, facultatif, valeur par défaut : -10) — Valeur utilisée pour rembourder les points d’entrée lors du groupement de séquences de longueurs différentes. Cette valeur sert à marquer les positions rembourdées et est conservée lors de la normalisation des coordonnées.

Construit un Sam3TrackerVideoProcessor qui encapsule un processeur d’images et un processeur de vidéos en un seul processeur.

Sam3TrackerVideoProcessor propose toutes les fonctionnalités de Sam3ImageProcessor et de video_processor_class. Consultez ~Sam3ImageProcessor et ~video_processor_class pour plus d’informations.

__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

Paramètres

  • images (Union[PIL.Image.Image, numpy.ndarray, torch.Tensor, list[PIL.Image.Image], list[numpy.ndarray], list[torch.Tensor]], facultatif) — Image à prétraiter. S'attend à une image unique ou à un lot d'images dont les valeurs de pixels vont de 0 à 255. Si vous passez des images dont les valeurs de pixels sont comprises entre 0 et 1, définissez do_rescale=False.
  • segmentation_maps (ImageInput, facultatif) — Les cartes de segmentation à traiter.
  • input_points (list[list[list[list[float]]]], torch.Tensor, facultatif) — Les points à ajouter au repère.
  • input_labels (list[list[list[int]]], torch.Tensor, facultatif) — Les étiquettes des points.
  • input_boxes (list[list[list[float]]], torch.Tensor, facultatif) — Les boîtes englobantes à ajouter à l'image.
  • original_sizes (list[list[float]], torch.Tensor, facultatif) — Les dimensions d'origine des images.
  • return_tensors (Union[str, ~utils.generic.TensorType], facultatif) — Si défini, renvoie des tenseurs d'un framework particulier. Les valeurs acceptables sont :
    • 'pt' : Renvoie des objets torch.Tensor de PyTorch.
    • 'np' : Renvoie des objets NumPy np.ndarray.

Retourne

Un BatchEncoding avec les champs suivants

  • pixel_values (torch.Tensor) : l’image (ou les images) traitée(s).
  • original_sizes (list[list[float]]) : Les dimensions d’origine des images.
  • labels (torch.Tensor) : les cartes de segmentation traitées (si fournies).
  • input_points (torch.Tensor) : Les points traités.
  • input_labels (torch.Tensor) : Les étiquettes traitées.
  • input_boxes (torch.Tensor) : Les boîtes englobantes traitées.

post_process_masks

< >

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

Paramètres

  • masks (Union[List[torch.Tensor], List[np.ndarray]]) — Masques par lot issus de mask_decoder, au format (batch_size, num_channels, height, width).
  • original_sizes (Union[torch.Tensor, List[Tuple[int,int]]]) — Les dimensions d’origine de chaque image avant son redimensionnement à la forme d’entrée attendue par le modèle, au format (hauteur, largeur).
  • mask_threshold (float, facultatif, valeur par défaut 0.0) — Seuil pour les opérations de binarisation et de post-traitement.
  • binarize (bool, facultatif, valeur par défaut True) — Indique s'il faut binariser les masques.
  • max_hole_area (float, facultatif, valeur par défaut 0.0) — La surface maximale d'un trou à combler.
  • max_sprinkle_area (float, facultatif, valeur par défaut 0.0) — La surface maximale d'un sprinkle à remplir.
  • apply_non_overlapping_constraints (bool, facultatif, valeur par défaut False) — Indique s'il faut appliquer des contraintes de non-chevauchement aux masques.

Retourne

(torch.Tensor)

Masques par lot au format batch_size, num_channels, height, width, où (height, width) est défini par original_size.

Supprimez le bourrage et redimensionnez les masques à la taille d'image d'origine.

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 )

Paramètres

  • video (VideoInput, facultatif) — La vidéo à traiter. Aucun besoin de la fournir lors d’un flux en continu.
  • inference_device (str ou torch.device, facultatif, par défaut “cpu”) — L’appareil à utiliser pour l’inférence.
  • inference_state_device (str ou torch.device, facultatif) — L'appareil sur lequel stocker l'état d'inférence.
  • processing_device (str ou torch.device, facultatif) — L'appareil à utiliser pour le traitement de la vidéo.
  • video_storage_device (str ou torch.device, facultatif) — L'appareil sur lequel stocker les images vidéo traitées.
  • max_vision_features_cache_size (int, facultatif, valeur par défaut 1) — Nombre maximal de fonctionnalités visuelles à mettre en cache.
  • dtype (torch.dtype, facultatif, par défaut torch.float32) — Le dtype torch à utiliser pour l'ensemble de la session.

Initialise une session vidéo pour l'inférence. Si une vidéo est fournie (inférence asynchrone), la vidéo sera traitée et stockée sur le 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 )

Paramètres

  • inference_session (Sam3TrackerVideoInferenceSession) — Session d'inférence pour la vidéo.
  • frame_idx (int) — L'index de la frame à traiter.
  • obj_ids (list[int] ou int) — L'identifiant (ou les identifiants) d'objet à associer au point ou à la boîte. Il peut s'agir de n'importe quels entiers, réutilisables plus tard pour désigner un objet.
  • input_points (list[list[list[list[float]]]], torch.Tensor, facultatif) — Les points à ajouter au repère.
  • input_labels (list[list[list[int]]], torch.Tensor, facultatif) — Les étiquettes des points.
  • input_boxes (list[list[list[float]]], torch.Tensor, facultatif) — Les boîtes englobantes à ajouter à l'image.
  • input_masks (np.ndarray, torch.Tensor, list[np.ndarray] ou list[torch.Tensor], facultatif) — Le(s) masque(s) à ajouter à la frame.
  • original_size (tuple[int, int], facultatif) — La taille d'origine de la vidéo. À fournir lors du streaming.
  • clear_old_inputs (bool, facultatif, valeur par défaut True) — Indique s'il faut effacer les anciennes entrées de l'objet.

Traitez de nouveaux points, boîtes ou masques pour une image vidéo et ajoutez-les à la session d'inférence.

Sam3TrackerVideoInferenceSession

classe transformers.Sam3TrackerVideoInferenceSession

< >

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

Paramètres

  • video (torch.Tensor, facultatif) — La vidéo à traiter. Inutile de la fournir lors d’un flux en continu.
  • video_height (int, facultatif) — La hauteur de la vidéo.
  • video_width (int, facultatif) — La largeur de la vidéo.
  • inference_device (torch.device, facultatif, par défaut "cpu") — L’appareil à utiliser pour l’inférence.
  • inference_state_device (torch.device, facultatif, par défaut "cpu") — L’appareil sur lequel stocker l’état d’inférence.
  • video_storage_device (torch.device, facultatif, par défaut "cpu") — L’appareil sur lequel stocker la vidéo.
  • dtype (torch.dtype, facultatif, par défaut "float32") — Le dtype à utiliser pour la vidéo.
  • max_vision_features_cache_size (int, facultatif, valeur par défaut 1) — Nombre maximal de fonctionnalités visuelles à mettre en cache.

Gère les paramètres, l'état et le cache des sessions d'inférence vidéo.

add_mask_inputs

< >

( obj_idx: intframe_idx: intinputs: Tensor )

Ajoutez des entrées de masque avec un placement automatique sur l'appareil.

add_new_frame

< >

( pixel_values: Tensorframe_idx: int | None = None )

Ajouter un nouveau frame avec un placement automatique des appareils.

add_point_inputs

< >

( obj_idx: intframe_idx: intinputs: dict )

Ajoutez des entrées de points avec un placement automatique sur l'appareil.

get_frame

< >

( frame_idx: int )

Obtenir une image à partir d'une vidéo.

get_obj_num

< >

( )

Obtenir le nombre total d'identifiants d'objets uniques reçus jusqu'à présent dans cette session.

get_output

< >

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

Paramètres

  • obj_idx (int) — L'index de l'objet.
  • frame_idx (int) — L'index de la frame.
  • output_key (str) — La clé de la sortie.
  • is_conditioning_frame (bool) — Indique si la sortie correspond à une image de conditionnement.

Obtenez la sortie avec une gestion intelligente des appareils.

obj_id_to_idx

< >

( obj_id: int )

Associer l'ID d'objet à un index, en créant une nouvelle entrée si nécessaire.

obj_idx_to_id

< >

( obj_idx: int )

Associer l'index d'objet côté modèle à l'identifiant d'objet côté client.

remove_mask_inputs

< >

( obj_idx: intframe_idx: int )

Supprimer les entrées de masque.

remove_point_inputs

< >

( obj_idx: intframe_idx: int )

Supprimer les entrées de points.

reset_inference_session

< >

( )

Réinitialiser les données de suivi et le cache.

reset_tracking_data

< >

( )

Réinitialiser les données de suivi mais conserver le cache.

store_output

< >

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

Paramètres

  • obj_idx (int) — L'index de l'objet.
  • frame_idx (int) — L'index de la frame.
  • output_key (Optional[str]) — La clé de la sortie. Si None, la sortie est stockée sous forme de dictionnaire.
  • output_value (Optional[Union[torch.Tensor, dict]]) — La valeur de la sortie.
  • is_conditioning_frame (bool) — Indique si la sortie correspond à une image de conditionnement.

Stockage de la sortie avec une gestion intelligente des appareils. Si output_key est None, la sortie est stockée sous forme de dictionnaire.

Sam3TrackerVideoModel

classe transformers.Sam3TrackerVideoModel

< >

( config: Sam3TrackerVideoConfigremove_vision_encoder: bool = False )

Paramètres

  • config (Sam3TrackerVideoConfig) — Classe de configuration du modèle contenant tous les paramètres du modèle. L'initialisation à partir d'un fichier de configuration ne charge pas les poids associés au modèle, uniquement la configuration. Consultez la méthode from_pretrained() pour charger les poids du modèle.
  • remove_vision_encoder (bool, facultatif, valeur par défaut False) — Indique s'il faut supprimer l'encodeur visuel. Si True, l'encodeur visuel est défini sur None.

Le modèle de suivi vidéo Sam3 brut, qui produit des états cachés bruts sans aucune tête spécifique au sommet.

Ce modèle hérite de PreTrainedModel. Consultez la documentation de la classe parente pour les méthodes génériques que la bibliothèque implémente pour tous ses modèles (tels que le téléchargement ou l'enregistrement, le redimensionnement des embeddings d'entrée, la taille des têtes, etc.)

Ce modèle est également une sous-classe de torch.nn.Module de PyTorch. Utilisez-le comme un module PyTorch standard et consultez la documentation de PyTorch pour tout ce qui concerne l'utilisation et le comportement généraux.

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)

Paramètres

  • inference_session (~models.sam3_tracker_video.modeling_sam3_tracker_video.Sam3TrackerVideoInferenceSession) — Objet de session d'inférence vidéo.
  • frame_idx (int, facultatif) — L’index de la frame sur laquelle exécuter l’inférence. Pas besoin de le fournir lors de l’inférence sur une nouvelle frame diffusée en continu.
  • frame (torch.Tensor, facultatif) — La frame à traiter. À fournir lors du streaming.
  • reverse (bool, facultatif, par défaut False) — Indique s'il faut propager en sens inverse.
  • run_mem_encoder (bool, facultatif, valeur par défaut True) — Indique s'il faut exécuter l'encodeur mémoire sur les masques prédits. L'encodeur mémoire est exécuté par lots sur tous les objets pour des raisons d'efficacité.

Retourne

Sam3TrackerVideoSegmentationOutput ou tuple(torch.Tensor)

Un Sam3TrackerVideoSegmentationOutput ou un tuple de torch.Tensor (si return_dict=False est passé ou lorsque config.return_dict=False) comprenant divers éléments en fonction de la configuration (Sam3TrackerVideoConfig) et des entrées.

Propagez les objets à travers une image vidéo diffusée en continu.

  • object_ids (list[int], facultatif) — Liste des identifiants d'objets suivis dans l'image actuelle.
  • pred_masks (torch.Tensor de forme (batch_size, num_masks, height, width)) — Les masques prédits stockés à la résolution du modèle.
  • object_score_logits (torch.Tensor de forme (batch_size,), facultatif) — Logits des scores d'objets, indiquant si des objets sont présents.
  • frame_idx (int, facultatif) — L'index de la frame de la vidéo.

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)

Paramètres

  • inference_session (~models.sam3_tracker_video.modeling_sam3_tracker_video.Sam3TrackerVideoInferenceSession) — Objet de session d'inférence vidéo.
  • start_frame_idx (int, facultatif) — Index de la première image pour la propagation. Doit être fourni si forward n’a pas encore été appelé sur de nouvelles entrées. S’il n’est pas fourni, l’index de la première image sera celui de l’image la plus ancienne contenant des points d’entrée.
  • max_frame_num_to_track (int, facultatif) — Nombre maximal de frames à suivre.
  • reverse (bool, facultatif, par défaut False) — Indique s'il faut propager en sens inverse.
  • show_progress_bar (bool, facultatif, valeur par défaut False) — Indique s'il faut afficher une barre de progression pendant la propagation.

Retourne

Sam3TrackerVideoSegmentationOutput ou tuple(torch.Tensor)

Un Sam3TrackerVideoSegmentationOutput ou un tuple de torch.Tensor (si return_dict=False est passé ou lorsque config.return_dict=False) comprenant divers éléments en fonction de la configuration (Sam3TrackerVideoConfig) et des entrées.

Propage les objets à travers les images de la vidéo. Utilisé lors de l’initialisation d’une session d’inférence avec une vidéo entière. Produit un Sam3TrackerVideoSegmentationOutput pour chaque image.

  • object_ids (list[int], facultatif) — Liste des identifiants d'objets suivis dans l'image actuelle.
  • pred_masks (torch.Tensor de forme (batch_size, num_masks, height, width)) — Les masques prédits stockés à la résolution du modèle.
  • object_score_logits (torch.Tensor de forme (batch_size,), facultatif) — Logits des scores d'objets, indiquant si des objets sont présents.
  • frame_idx (int, facultatif) — L'index de la frame de la vidéo.

get_image_features

< >

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

Paramètres

  • pixel_values (torch.Tensor) — Valeurs de pixels d'entrée de forme (batch_size, num_channels, height, width).

Retourne

Sam3TrackerVideoVisionEncoderOutput ou tuple(torch.Tensor)

Un Sam3TrackerVideoVisionEncoderOutput ou un tuple de torch.Tensor (si return_dict=False est passé ou lorsque config.return_dict=False) comprenant divers éléments en fonction de la configuration (Sam3TrackerVideoConfig) et des entrées.

  • last_hidden_state (torch.Tensor de forme (batch_size, height, width, hidden_size)) — Séquence d'états cachés à la sortie de la dernière couche du modèle.

  • pooler_output (torch.Tensor de forme (batch_size, hidden_size)) — État caché de la dernière couche du premier jeton de la séquence (jeton de classification) après un traitement supplémentaire par les couches utilisées pour la tâche de pré-entraînement auxiliaire. Par exemple, pour les modèles de la famille BERT, cela renvoie le jeton de classification après traitement par une couche linéaire et une fonction d'activation tanh. Les poids de la couche linéaire sont entraînés à partir de l'objectif de prédiction de la phrase suivante (classification) pendant le pré-entraînement.

  • hidden_states (tuple(torch.Tensor), facultatif, renvoyé lorsque output_hidden_states=True est passé ou lorsque config.output_hidden_states=True) — Tuple de torch.Tensor (un pour la sortie des embeddings, si le modèle possède une couche d’embedding, + un pour la sortie de chaque couche) de forme (batch_size, sequence_length, hidden_size).

    États cachés du modèle à la sortie de chaque couche, ainsi que les sorties d'incorporation initiales facultatives.

  • attentions (tuple(torch.Tensor), facultatif, renvoyé lorsque output_attentions=True est passé ou lorsque config.output_attentions=True) — Tuple de torch.Tensor (un par couche) de forme (batch_size, num_heads, sequence_length, sequence_length).

    Poids des attentions après le softmax d'attention, utilisés pour calculer la moyenne pondérée dans les têtes d'auto-attention.

  • fpn_hidden_states (tuple(torch.Tensor)) — Tuple de torch.Tensor (un pour chaque niveau de caractéristique, de la résolution la plus haute à la plus basse) de forme (batch_size, hidden_size, height, width). Cartes de caractéristiques issues du cou Feature Pyramid Network.

  • fpn_position_encoding (tuple(torch.Tensor)) — Tuple de torch.Tensor (un pour chaque niveau de caractéristiques, de la résolution la plus haute à la plus basse) de forme (batch_size, hidden_size, height, width). Encodages positionnels correspondant aux fpn_hidden_states.

Update on GitHub

←SAM2 Vidéo TimeSformer→