# SAM3 Tracker Vidéo

    
        
        
    

## Aperçu

SAM3 (Segment Anything Model 3) a été introduit dans [SAM 3: Segment Anything with Concepts](https://ai.meta.com/research/publications/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 pilotée par prompts (Promptable Concept Segmentation, 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é comportant 4 millions d’étiquettes de concepts uniques, incluant des négatifs difficiles, sur des images et des vidéos. Notre modèle est composé d’un détecteur au niveau de l’image et d’un suiveur vidéo basé sur la mémoire qui partagent un même 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-sourçons SAM 3 ainsi que notre nouveau benchmark Segment Anything with Concepts (SA-Co) pour la segmentation de concepts pilotée par prompts.*

Ce modèle a été contribué par [yonigozlan](https://huggingface.co/yonigozlan) et [ronghanghu](https://huggingface.co/ronghanghu).

## Exemple d'utilisation

### Segmentation et suivi vidéo

#### Suivi vidéo de base

```python
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 :

```python
# 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 :

```python
# 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 :

```python
# 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 :

```python
# 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.Sam3TrackerVideoConfig[[transformers.Sam3TrackerVideoConfig]]

```python
transformers.Sam3TrackerVideoConfig(transformers_version: str | None = None, architectures: list[str] | None = None, output_hidden_states: bool | None = False, return_dict: bool | None = True, dtype: str | torch.dtype | None = None, chunk_size_feed_forward: int = 0, is_encoder_decoder: bool = False, id2label: dict[int, str] | dict[str, str] | None = None, label2id: dict[str, int] | dict[str, str] | None = None, problem_type: Literal['regression', 'single_label_classification', 'multi_label_classification'] | None = None, vision_config: dict | transformers.configuration_utils.PreTrainedConfig | None = None, prompt_encoder_config: dict | transformers.configuration_utils.PreTrainedConfig | None = None, mask_decoder_config: dict | transformers.configuration_utils.PreTrainedConfig | None = None, 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, 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 | int = 0.1, memory_attention_rope_feat_sizes: list | None = None, memory_attention_rope_dropout: float | int = 0.1, memory_encoder_hidden_size: int = 256, memory_encoder_output_channels: int = 64, rope_parameters: dict | None = None, 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_kernel_size: int = 7, memory_fuser_padding: int = 3, memory_fuser_layer_scale_init_value: float = 1e-06, memory_fuser_hidden_act: str = 'gelu')
```

[Source](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/sam3_tracker_video/configuration_sam3_tracker_video.py#L99)

**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](/docs/transformers/v5.23.0/fr/model_doc/sam3_tracker_video#transformers.Sam3TrackerVideoPromptEncoderConfig).

mask_decoder_config (Union[`dict`, `Sam3TrackerVideoMaskDecoderConfig`], *facultatif*) : Dictionnaire des options de configuration utilisées pour initialiser [Sam3TrackerVideoMaskDecoderConfig](/docs/transformers/v5.23.0/fr/model_doc/sam3_tracker_video#transformers.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 du 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'intégration spatiale pour les occlusions.

multimask_output_in_sam (`bool`, *facultatif*, valeur 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) : Nombre maximal de points pour déclencher la sortie multimask.

multimask_output_for_tracking (`bool`, *facultatif*, valeur par défaut `True`) : Indique s'il faut utiliser une sortie multimasque pour le suivi.

max_object_pointers_in_encoder (`int`, *facultatif*, valeur par défaut : 16) : 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 le codage 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 dans le 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*, valeur 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) : Le 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 des caractéristiques pour l'encodage positionnel Rope.

memory_attention_rope_dropout (`float`, *facultatif*, valeur par défaut 0,1) : Le 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 pour les 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 réducteur de masque.

mask_downsampler_kernel_size (`int`, *facultatif*, valeur par défaut : 3) : La taille du noyau pour le sous-échantillonneur de masque.

mask_downsampler_stride (`int`, *facultatif*, valeur par défaut : 2) : Le pas (stride) pour le sous-échantillonneur de masque.

mask_downsampler_padding (`int`, *facultatif*, valeur par défaut : 1) : Le padding pour le sous-échantillonneur de masque.

mask_downsampler_total_stride (`int`, *facultatif*, par défaut 16) : Le pas total pour le sous-échantillonneur de masque.

mask_downsampler_hidden_act (`str`, *facultatif*, valeur par défaut `"gelu"`) : Fonction d'activation non linéaire du 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'incorporation dans le fuser mémoire.

memory_fuser_intermediate_dim (`int`, *facultatif*, valeur par défaut 1024) : La dimension de la couche intermédiaire dans le fuser mémoire.

memory_fuser_kernel_size (`int`, *facultatif*, par défaut 7) : La taille du noyau pour le fuser de mémoire.

memory_fuser_padding (`int`, *facultatif*, valeur par défaut : 3) : Le padding pour le fuser mémoire.

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"`) : Fonction d'activation non linéaire dans le fuser mémoire.

Il s'agit de la classe de configuration destinée à 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](https://huggingface.co/facebook/sam3)

Les objets de configuration héritent de [PreTrainedConfig](/docs/transformers/v5.23.0/fr/main_classes/configuration#transformers.PreTrainedConfig) et peuvent être utilisés pour contrôler les sorties du modèle. Consultez la documentation de [PreTrainedConfig](/docs/transformers/v5.23.0/fr/main_classes/configuration#transformers.PreTrainedConfig) pour plus d’informations.

Exemple :

```python
>>> 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.Sam3TrackerVideoMaskDecoderConfig[[transformers.Sam3TrackerVideoMaskDecoderConfig]]

```python
transformers.Sam3TrackerVideoMaskDecoderConfig(transformers_version: str | None = None, architectures: list[str] | None = None, output_hidden_states: bool | None = False, return_dict: bool | None = True, dtype: str | torch.dtype | None = None, chunk_size_feed_forward: int = 0, is_encoder_decoder: bool = False, id2label: dict[int, str] | dict[str, str] | None = None, label2id: dict[str, int] | dict[str, str] | None = None, problem_type: Literal['regression', 'single_label_classification', 'multi_label_classification'] | None = None, hidden_size: int = 256, hidden_act: str = 'gelu', mlp_dim: int = 2048, num_hidden_layers: int = 2, num_attention_heads: int = 8, attention_downsample_rate: int = 2, num_multimask_outputs: int = 3, iou_head_depth: int = 3, iou_head_hidden_dim: int = 256, dynamic_multimask_via_stability: bool = True, dynamic_multimask_stability_delta: float = 0.05, dynamic_multimask_stability_thresh: float = 0.98)
```

[Source](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/sam3_tracker_video/configuration_sam3_tracker_video.py#L60)

**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) dans le décodeur. Par exemple, `"gelu"`, `"relu"`, `"silu"`, etc.

mlp_dim (`int`, *facultatif*, valeur par défaut 2048) : La dimension du MLP dans le transformeur bidirectionnel.

num_hidden_layers (`int`, *facultatif*, valeur 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) : Le delta de stabilité pour le multimask dynamique.

dynamic_multimask_stability_thresh (`float`, *facultatif*, valeur par défaut 0.98) : Le seuil de stabilité pour le multimask dynamique.

Il s'agit de la classe de configuration destinée à 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](https://huggingface.co/facebook/sam3)

Les objets de configuration héritent de [PreTrainedConfig](/docs/transformers/v5.23.0/fr/main_classes/configuration#transformers.PreTrainedConfig) et peuvent être utilisés pour contrôler les sorties du modèle. Consultez la documentation de [PreTrainedConfig](/docs/transformers/v5.23.0/fr/main_classes/configuration#transformers.PreTrainedConfig) pour plus d’informations.

## Sam3TrackerVideoPromptEncoderConfig[[transformers.Sam3TrackerVideoPromptEncoderConfig]]

#### transformers.Sam3TrackerVideoPromptEncoderConfig[[transformers.Sam3TrackerVideoPromptEncoderConfig]]

```python
transformers.Sam3TrackerVideoPromptEncoderConfig(transformers_version: str | None = None, architectures: list[str] | None = None, output_hidden_states: bool | None = False, return_dict: bool | None = True, dtype: str | torch.dtype | None = None, chunk_size_feed_forward: int = 0, is_encoder_decoder: bool = False, id2label: dict[int, str] | dict[str, str] | None = None, label2id: dict[str, int] | dict[str, str] | None = None, problem_type: Literal['regression', 'single_label_classification', 'multi_label_classification'] | None = None, hidden_size: int = 256, image_size: int | list[int] | tuple[int, int] = 1008, patch_size: int | list[int] | tuple[int, int] = 14, mask_input_channels: int = 16, num_point_embeddings: int = 4, hidden_act: str = 'gelu', layer_norm_eps: float = 1e-06, scale: int = 1)
```

[Source](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/sam3_tracker_video/configuration_sam3_tracker_video.py#L34)

**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*, valeur par défaut `1008`) : La taille (résolution) de chaque image.

patch_size (`Union[int, list[int], tuple[int, int]]`, *facultatif*, valeur 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*, valeur 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) dans le décodeur. Par exemple, `"gelu"`, `"relu"`, `"silu"`, etc.

layer_norm_eps (`float`, *facultatif*, par défaut `1e-06`) : L'épsilon utilisé par les couches de normalisation par 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 destinée à 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](https://huggingface.co/facebook/sam3)

Les objets de configuration héritent de [PreTrainedConfig](/docs/transformers/v5.23.0/fr/main_classes/configuration#transformers.PreTrainedConfig) et peuvent être utilisés pour contrôler les sorties du modèle. Consultez la documentation de [PreTrainedConfig](/docs/transformers/v5.23.0/fr/main_classes/configuration#transformers.PreTrainedConfig) pour plus d’informations.

## Sam3TrackerVideoProcessor[[transformers.Sam3TrackerVideoProcessor]]

#### transformers.Sam3TrackerVideoProcessor[[transformers.Sam3TrackerVideoProcessor]]

```python
transformers.Sam3TrackerVideoProcessor(image_processor, video_processor, target_size: int | None = None, point_pad_value: int = -10, **kwargs)
```

[Source](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/sam3_tracker_video/processing_sam3_tracker_video.py#L39)

**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*) : La taille cible (en pixels) pour normaliser les points d'entrée et les boîtes englobantes. 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) : La valeur utilisée pour rembourner les points d'entrée lors du groupement de séquences de longueurs différentes. Cette valeur sert à marquer les positions rembourré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](/docs/transformers/v5.23.0/fr/model_doc/sam3_tracker_video#transformers.Sam3TrackerVideoProcessor) propose toutes les fonctionnalités de [Sam3ImageProcessor](/docs/transformers/v5.23.0/fr/model_doc/sam3#transformers.Sam3ImageProcessor) et de `video_processor_class`. Consultez [~Sam3ImageProcessor](/docs/transformers/v5.23.0/fr/model_doc/sam3#transformers.Sam3ImageProcessor) et `~video_processor_class` pour plus d’informations.

#### __appel__[[transformers.Sam3TrackerVideoProcessor.__call__]]

```python
__call__(images: typing.Union[ForwardRef('PIL.Image.Image'), numpy.ndarray, ForwardRef('torch.Tensor'), list['PIL.Image.Image'], list[numpy.ndarray], list['torch.Tensor'], NoneType] = None, segmentation_maps: typing.Union[ForwardRef('PIL.Image.Image'), numpy.ndarray, ForwardRef('torch.Tensor'), list['PIL.Image.Image'], list[numpy.ndarray], list['torch.Tensor'], NoneType] = None, input_points: typing.Union[list[list[list[list[float]]]], torch.Tensor, NoneType] = None, input_labels: typing.Union[list[list[list[int]]], torch.Tensor, NoneType] = None, input_boxes: typing.Union[list[list[list[float]]], torch.Tensor, NoneType] = None, original_sizes: typing.Union[list[list[float]], torch.Tensor, NoneType] = None, return_tensors: str | transformers.utils.generic.TensorType | None = None, **kwargs)
```

[Source](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/sam3_tracker_video/processing_sam3_tracker_video.py#L57)

**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. Attend une image unique ou un lot d'images dont les valeurs de pixels sont comprises entre 0 et 255. Si vous transmettez 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, renverra des tenseurs d'un framework particulier. Les valeurs acceptables sont :  - `'pt'` : Renvoie des objets `torch.Tensor` de PyTorch. - `'np'` : Renvoie des objets `np.ndarray` de NumPy.

**Retourne :** un [BatchEncoding](/docs/transformers/v5.23.0/fr/main_classes/tokenizer#transformers.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[[transformers.Sam3TrackerVideoProcessor.post_process_masks]]

```python
post_process_masks(masks, original_sizes, mask_threshold = 0.0, binarize = True, max_hole_area = 0.0, max_sprinkle_area = 0.0, apply_non_overlapping_constraints = False, **kwargs)
```

[Source](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/sam3_tracker_video/processing_sam3_tracker_video.py#L463)

**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 point à 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 lots 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[[transformers.Sam3TrackerVideoProcessor.init_video_session]]

```python
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] = None, inference_device: typing.Union[str, ForwardRef('torch.device')] = 'cpu', inference_state_device: typing.Union[str, ForwardRef('torch.device'), NoneType] = None, processing_device: typing.Union[str, ForwardRef('torch.device'), NoneType] = None, video_storage_device: typing.Union[str, ForwardRef('torch.device'), NoneType] = None, max_vision_features_cache_size: int = 1, dtype: dtype = torch.float32)
```

[Source](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/sam3_tracker_video/processing_sam3_tracker_video.py#L514)

**Paramètres :**

video (`VideoInput`, *facultatif*) : La vidéo à traiter. Aucun besoin de la fournir lors du streaming.

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 de déduction.

processing_device (`str` ou `torch.device`, *facultatif*) : L'appareil à utiliser pour le traitement 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), elle sera traitée et stockée sur le `video_storage_device`.

#### add_inputs_to_inference_session[[transformers.Sam3TrackerVideoProcessor.add_inputs_to_inference_session]]

```python
add_inputs_to_inference_session(inference_session: Sam3TrackerVideoInferenceSession, frame_idx: int, obj_ids: list[int] | int, input_points: typing.Union[list[list[list[list[float]]]], torch.Tensor, NoneType] = None, input_labels: typing.Union[list[list[list[int]]], torch.Tensor, NoneType] = None, input_boxes: typing.Union[list[list[list[float]]], torch.Tensor, NoneType] = None, input_masks: typing.Union[numpy.ndarray, torch.Tensor, list[numpy.ndarray], list[torch.Tensor], NoneType] = None, original_size: tuple[int, int] | None = None, clear_old_inputs: bool = True)
```

[Source](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/sam3_tracker_video/processing_sam3_tracker_video.py#L567)

**Paramètres :**

inference_session (`Sam3TrackerVideoInferenceSession`) : la 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 aux points 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 trame.

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[[transformers.Sam3TrackerVideoInferenceSession]]

#### transformers.Sam3TrackerVideoInferenceSession[[transformers.Sam3TrackerVideoInferenceSession]]

```python
transformers.Sam3TrackerVideoInferenceSession(video: typing.Optional[torch.Tensor] = None, video_height: int | None = None, video_width: int | None = None, inference_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)
```

[Source](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/sam3_tracker_video/modeling_sam3_tracker_video.py#L109)

**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 de déduction.

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[[transformers.Sam3TrackerVideoInferenceSession.add_mask_inputs]]

```python
add_mask_inputs(obj_idx: int, frame_idx: int, inputs: Tensor)
```

[Source](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/sam3_tracker_video/modeling_sam3_tracker_video.py#L229)

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

#### add_new_frame[[transformers.Sam3TrackerVideoInferenceSession.add_new_frame]]

```python
add_new_frame(pixel_values: Tensor, frame_idx: int | None = None)
```

[Source](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/sam3_tracker_video/modeling_sam3_tracker_video.py#L304)

Ajouter un nouveau frame avec un placement automatique des appareils.

#### add_point_inputs[[transformers.Sam3TrackerVideoInferenceSession.add_point_inputs]]

```python
add_point_inputs(obj_idx: int, frame_idx: int, inputs: dict)
```

[Source](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/sam3_tracker_video/modeling_sam3_tracker_video.py#L215)

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

#### get_frame[[transformers.Sam3TrackerVideoInferenceSession.get_frame]]

```python
get_frame(frame_idx: int)
```

[Source](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/sam3_tracker_video/modeling_sam3_tracker_video.py#L320)

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

#### get_obj_num[[transformers.Sam3TrackerVideoInferenceSession.get_obj_num]]

```python
get_obj_num()
```

[Source](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/sam3_tracker_video/modeling_sam3_tracker_video.py#L210)

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

#### get_output[[transformers.Sam3TrackerVideoInferenceSession.get_output]]

```python
get_output(obj_idx: int, frame_idx: int, output_key: str, is_conditioning_frame: bool = True)
```

[Source](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/sam3_tracker_video/modeling_sam3_tracker_video.py#L277)

**Paramètres :**

obj_idx (int) : L'index de l'objet.

frame_idx (int) : L'index de la trame.

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[[transformers.Sam3TrackerVideoInferenceSession.obj_id_to_idx]]

```python
obj_id_to_idx(obj_id: int)
```

[Source](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/sam3_tracker_video/modeling_sam3_tracker_video.py#L184)

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

#### obj_idx_to_id[[transformers.Sam3TrackerVideoInferenceSession.obj_idx_to_id]]

```python
obj_idx_to_id(obj_idx: int)
```

[Source](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/sam3_tracker_video/modeling_sam3_tracker_video.py#L206)

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

#### remove_mask_inputs[[transformers.Sam3TrackerVideoInferenceSession.remove_mask_inputs]]

```python
remove_mask_inputs(obj_idx: int, frame_idx: int)
```

[Source](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/sam3_tracker_video/modeling_sam3_tracker_video.py#L235)

Supprimer les entrées de masque.

#### remove_point_inputs[[transformers.Sam3TrackerVideoInferenceSession.remove_point_inputs]]

```python
remove_point_inputs(obj_idx: int, frame_idx: int)
```

[Source](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/sam3_tracker_video/modeling_sam3_tracker_video.py#L225)

Supprimer les entrées de points.

#### reset_inference_session[[transformers.Sam3TrackerVideoInferenceSession.reset_inference_session]]

```python
reset_inference_session()
```

[Source](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/sam3_tracker_video/modeling_sam3_tracker_video.py#L336)

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

#### reset_tracking_data[[transformers.Sam3TrackerVideoInferenceSession.reset_tracking_data]]

```python
reset_tracking_data()
```

[Source](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/sam3_tracker_video/modeling_sam3_tracker_video.py#L324)

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

#### store_output[[transformers.Sam3TrackerVideoInferenceSession.store_output]]

```python
store_output(obj_idx: int, frame_idx: int, output_key: str | None = None, output_value: typing.Union[torch.Tensor, dict, NoneType] = None, is_conditioning_frame: bool = True)
```

[Source](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/sam3_tracker_video/modeling_sam3_tracker_video.py#L240)

**Paramètres :**

obj_idx (int) : L'index de l'objet.

frame_idx (int) : L'index de la trame.

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.

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

## Sam3TrackerVideoModel[[transformers.Sam3TrackerVideoModel]]

#### transformers.Sam3TrackerVideoModel[[transformers.Sam3TrackerVideoModel]]

```python
transformers.Sam3TrackerVideoModel(config: Sam3TrackerVideoConfig, remove_vision_encoder: bool = False)
```

[Source](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/sam3_tracker_video/modeling_sam3_tracker_video.py#L1647)

**Paramètres :**

config ([Sam3TrackerVideoConfig](/docs/transformers/v5.23.0/fr/model_doc/sam3_tracker_video#transformers.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()](/docs/transformers/v5.23.0/fr/main_classes/model#transformers.PreTrainedModel.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](/docs/transformers/v5.23.0/fr/main_classes/model#transformers.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, l'élagage des têtes, etc.).

Ce modèle est également une sous-classe de [torch.nn.Module](https://pytorch.org/docs/stable/nn.html#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[[transformers.Sam3TrackerVideoModel.forward]]

```python
forward(inference_session: Sam3TrackerVideoInferenceSession, frame_idx: int | None = None, frame: typing.Optional[torch.Tensor] = None, reverse: bool = False, run_mem_encoder: bool = True, **kwargs)
```

[Source](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/sam3_tracker_video/modeling_sam3_tracker_video.py#L1789)

**Paramètres :**

inference_session (`~models.sam3_tracker_video.modeling_sam3_tracker_video.Sam3TrackerVideoInferenceSession`) : l'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 trame à 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 groupé par lot pour tous les objets afin d'optimiser l'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 selon la configuration ([Sam3TrackerVideoConfig](/docs/transformers/v5.23.0/fr/model_doc/sam3_tracker_video#transformers.Sam3TrackerVideoConfig)) et les 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 courante.
- **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[[transformers.Sam3TrackerVideoModel.propagate_in_video_iterator]]

```python
propagate_in_video_iterator(inference_session: Sam3TrackerVideoInferenceSession, start_frame_idx: int | None = None, max_frame_num_to_track: int | None = None, reverse: bool = False, show_progress_bar: bool = False)
```

[Source](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/sam3_tracker_video/modeling_sam3_tracker_video.py#L2812)

**Paramètres :**

inference_session (`~models.sam3_tracker_video.modeling_sam3_tracker_video.Sam3TrackerVideoInferenceSession`) : l'objet de session d'inférence vidéo.

start_frame_idx (`int`, *facultatif*) : L'index de la frame de départ 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 frame de départ sera la frame 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*, 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 selon la configuration ([Sam3TrackerVideoConfig](/docs/transformers/v5.23.0/fr/model_doc/sam3_tracker_video#transformers.Sam3TrackerVideoConfig)) et les 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 courante.
- **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[[transformers.Sam3TrackerVideoModel.get_image_features]]

```python
get_image_features(pixel_values: Tensor, **kwargs: *<class 'transformers.utils.generic.TransformersKwargs'>)
```

[Source](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/sam3_tracker_video/modeling_sam3_tracker_video.py#L1914)

**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 selon la configuration ([Sam3TrackerVideoConfig](/docs/transformers/v5.23.0/fr/model_doc/sam3_tracker_video#transformers.Sam3TrackerVideoConfig)) et les 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)`.

  Pondérations des attentions après le softmax d'attention, utilisées 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`.

