# SAM3 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/).

SAM3 Video effectue le **segmentation de concepts sur demande (PCS)** sur des vidéos. Le PCS prend du texte en entrée (par exemple, « bus scolaire jaune ») et prédit des masques d’instance et sémantiques pour **chaque objet** correspondant au concept, tout en préservant l’identité des objets d’un frame à l’autre.

Le modèle combine un module de détection (SAM3) avec un module de suivi (traceur de type SAM2) afin de permettre un suivi robuste d'objets à travers les images vidéo à l'aide de prompts textuels.

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

#### Inférence vidéo préchargée

Traiter une vidéo dont toutes les images sont déjà disponibles à l'aide de prompts texte :

```python
from transformers import Sam3VideoModel, Sam3VideoProcessor
import torch

model = Sam3VideoModel.from_pretrained("facebook/sam3", device_map="auto")
processor = Sam3VideoProcessor.from_pretrained("facebook/sam3")

# Load video frames
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,
    processing_device="cpu",
    video_storage_device="cpu",
)

# Add text prompt to detect and track objects
text = "person"
inference_session = processor.add_text_prompt(
    inference_session=inference_session,
    text=text,
)

# Process all frames in the video
outputs_per_frame = {}
# Pass show_progress_bar=True to display a tqdm progress bar.
for model_outputs in model.propagate_in_video_iterator(
    inference_session=inference_session, max_frame_num_to_track=50
):
    processed_outputs = processor.postprocess_outputs(inference_session, model_outputs)
    outputs_per_frame[model_outputs.frame_idx] = processed_outputs

print(f"Processed {len(outputs_per_frame)} frames")
Processed 51 frames

# Access results for a specific frame
frame_0_outputs = outputs_per_frame[0]
print(f"Detected {len(frame_0_outputs['object_ids'])} objects")
print(f"Object IDs: {frame_0_outputs['object_ids'].tolist()}")
print(f"Scores: {frame_0_outputs['scores'].tolist()}")
print(f"Boxes shape (XYXY format, absolute coordinates): {frame_0_outputs['boxes'].shape}")
print(f"Masks shape: {frame_0_outputs['masks'].shape}")
```

Vous pouvez également suivre simultanément plusieurs catégories d’objets en fournissant plusieurs prompts. Le modèle réutilise efficacement les caractéristiques visuelles pour tous les prompts :

```python
# Add multiple text prompts (or use a list in add_text_prompt)
multi_prompt_session = processor.init_video_session(
    video=video_frames,
    inference_device=device,
    processing_device="cpu",
    video_storage_device="cpu",
)
>>>
prompts = ["person", "bed", "lamp"]
processor.add_text_prompt(multi_prompt_session, prompts)
>>>
# Process video - detects objects from ALL prompts in a single pass
multi_outputs_per_frame = {}
# Pass show_progress_bar=True to display a tqdm progress bar.
for model_outputs in model.propagate_in_video_iterator(
    inference_session=multi_prompt_session, max_frame_num_to_track=50
):
    processed_outputs = processor.postprocess_outputs(multi_prompt_session, model_outputs)
    multi_outputs_per_frame[model_outputs.frame_idx] = processed_outputs
>>>
# Check which objects were detected by each prompt
frame_0_outputs = multi_outputs_per_frame[0]
prompt_to_obj_ids = frame_0_outputs["prompt_to_obj_ids"]
for prompt, obj_ids in prompt_to_obj_ids.items():
    print(f"{prompt}: {len(obj_ids)} objects")
person: 2 objects
bed: 1 objects
lamp: 1 objects
```

#### Inférence vidéo en streaming

⚠️ **Note sur la qualité de l'inférence en streaming** : l'inférence en streaming désactive les heuristiques de démarrage à chaud qui suppriment les objets non appariés et les objets en double, car celles-ci nécessitent un accès aux images futures pour prendre des décisions éclairées. Cela peut entraîner un plus grand nombre de fausses détections positives et de trajectoires d'objets en double par rapport à l'inférence sur vidéo préchargée. Pour de meilleurs résultats, utilisez l'inférence sur vidéo préchargée lorsque toutes les images sont disponibles.

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

```python
# Initialize session for streaming
streaming_inference_session = processor.init_video_session(
    inference_device=device,
    processing_device="cpu",
    video_storage_device="cpu",
)

# Add text prompt
text = "person"
streaming_inference_session = processor.add_text_prompt(
    inference_session=streaming_inference_session,
    text=text,
)

# Process frames one by one (streaming mode)
streaming_outputs_per_frame = {}
for frame_idx, frame in enumerate(video_frames[:50]):  # Process first 50 frames
    # First, process the frame using the processor
    inputs = processor(images=frame, device=device, return_tensors="pt").to(model.device)
...
    # Process frame using streaming inference - pass the processed pixel_values
    model_outputs = model(
        inference_session=streaming_inference_session,
        frame=inputs.pixel_values[0],  # Provide processed frame - this enables streaming mode
        reverse=False,
    )
...
    # Post-process outputs with original_sizes for proper resolution handling
    processed_outputs = processor.postprocess_outputs(
        streaming_inference_session,
        model_outputs,
        original_sizes=inputs.original_sizes,  # Required for streaming inference
    )
    streaming_outputs_per_frame[frame_idx] = processed_outputs
...
    if (frame_idx + 1) % 10 == 0:
        print(f"Processed {frame_idx + 1} frames...")

print(f"✓ Streaming inference complete! Processed {len(streaming_outputs_per_frame)} frames")
✓ Streaming inference complete! Processed 50 frames

# Access results
frame_0_outputs = streaming_outputs_per_frame[0]
print(f"Detected {len(frame_0_outputs['object_ids'])} objects in first frame")
print(f"Boxes are in XYXY format (absolute pixel coordinates): {frame_0_outputs['boxes'].shape}")
print(f"Masks are at original video resolution: {frame_0_outputs['masks'].shape}")
```

#### Inférence à résolution personnalisée

⚠️ **Note sur les performances** : les résolutions personnalisées peuvent dégrader la précision. Le modèle est conçu pour être utilisé à une résolution de 1008 px.

Pour une inférence plus rapide ou une consommation mémoire réduite :

```python
config = Sam3VideoConfig.from_pretrained("facebook/sam3")
config.image_size = 560
model = Sam3VideoModel.from_pretrained("facebook/sam3", config=config, device_map="auto")
processor = Sam3VideoProcessor.from_pretrained("facebook/sam3", size={"height": 560, "width": 560})
```

## Sam3VideoConfig[[transformers.Sam3VideoConfig]]

#### transformers.Sam3VideoConfig[[transformers.Sam3VideoConfig]]

```python
transformers.Sam3VideoConfig(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, detector_config: dict | transformers.configuration_utils.PreTrainedConfig | None = None, tracker_config: dict | transformers.configuration_utils.PreTrainedConfig | None = None, initializer_range: float = 0.02, low_res_mask_size: int = 288, score_threshold_detection: float = 0.5, det_nms_thresh: float = 0.1, assoc_iou_thresh: float = 0.1, trk_assoc_iou_thresh: float = 0.5, new_det_thresh: float = 0.7, recondition_on_trk_masks: bool = True, hotstart_delay: int = 15, hotstart_unmatch_thresh: int = 8, hotstart_dup_thresh: int = 8, suppress_unmatched_only_within_hotstart: bool = True, init_trk_keep_alive: int = 30, max_trk_keep_alive: int = 30, min_trk_keep_alive: int = -1, suppress_overlapping_based_on_recent_occlusion_threshold: float = 0.7, decrease_trk_keep_alive_for_empty_masklets: bool = False, fill_hole_area: int = 16, max_num_objects: int = 10000, recondition_every_nth_frame: int = 16, high_conf_thresh: float = 0.8, high_iou_thresh: float = 0.8)
```

[Source](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/sam3_video/configuration_sam3_video.py#L28)

**Paramètres :**

detector_config (`dict` ou `Sam3Config`, *facultatif*) : Configuration pour le modèle de détecteur Sam3. Si aucune configuration n'est fournie, la configuration Sam3Config par défaut sera utilisée.

tracker_config (`dict` ou `Sam2VideoConfig`, *facultatif*) : Configuration pour le modèle de suivi Sam2Video. Si aucune configuration n'est fournie, la configuration Sam2VideoConfig par défaut sera utilisée.

initializer_range (`float`, *facultatif*, valeur par défaut 0.02) : L'écart-type de la truncated_normal_initializer pour l'initialisation des matrices de poids.

low_res_mask_size (`int`, *facultatif*, valeur par défaut : 288) : Taille (hauteur et largeur) des masques de basse résolution produits par le tracker avant le redimensionnement à la résolution de la vidéo.

score_threshold_detection (`float`, *facultatif*, valeur par défaut 0,5) : Seuil de probabilité pour les sorties de détection - ne conserver que les détections supérieures à ce seuil.

det_nms_thresh (`float`, *facultatif*, par défaut 0.1) : seuil d'IoU pour la NMS (Non-Maximum Suppression) de détection.

assoc_iou_thresh (`float`, *facultatif*, valeur par défaut 0,1) : Seuil d'IoU pour l'appariement détection-piste. Une détection est considérée comme « appariée » à un tracklet si son chevauchement avec le tracklet dépasse ce seuil. Il s'agit souvent d'un seuil large, comme 0,1.

trk_assoc_iou_thresh (`float`, *facultatif*, valeur par défaut 0,5) : Seuil d'IoU pour l'appariement détection-suivi, utilisé pour déterminer si un masklet est « non apparié » par toutes les détections. Un seuil plus strict, comme 0,5, est souvent utilisé.

new_det_thresh (`float`, *facultatif*, valeur par défaut 0,7) : Seuil de probabilité pour qu'une détection soit ajoutée en tant que nouvel objet.

recondition_on_trk_masks (`bool`, *facultatif*, valeur par défaut `True`) : Indique s'il faut utiliser des masques suivis (True) ou des masques de détection (False) pour la reconditionnement. Utilisez True lorsque les masques suivis sont de meilleure qualité et que le détecteur sert de signal de validation pour renforcer la mémoire et prévenir la dérive.

hotstart_delay (`int`, *facultatif*, valeur par défaut : 15) : Nombre d'images à mettre en tampon pour les sorties pendant le hotstart. Nous retenons les sorties pendant `hotstart_delay` images et supprimons les tracklets en fonction des heuristiques de hotstart.

hotstart_unmatch_thresh (`int`, *facultatif*, valeur par défaut : 8) : Nombre de frames non appariées nécessaires pour supprimer un tracklet pendant la période de hotstart.

hotstart_dup_thresh (`int`, *facultatif*, valeur par défaut : 8) : Nombre de cadres superposés requis pour supprimer un tracklet en double pendant la période de hotstart.

suppress_unmatched_only_within_hotstart (`bool`, *facultatif*, valeur par défaut `True`) : Indique s'il faut supprimer les masques uniquement au cours de la période de préchauffage. Si la valeur est False, les masques peuvent être supprimés même s'ils commencent avant la période de préchauffage.

init_trk_keep_alive (`int`, *facultatif*, valeur par défaut : 30) : Compteur de maintien de connexion initial pour les nouvelles pistes.

max_trk_keep_alive (`int`, *facultatif*, valeur par défaut : 30) : Valeur maximale du compteur de maintien de la connexion. Les détections appariées voient leur compteur incrémenté jusqu'à cette valeur.

min_trk_keep_alive (`int`, *facultatif*, valeur par défaut : -1) : Valeur minimale du compteur de maintien en vie. Les trajectoires associées à des détections non appariées voient leur compteur diminué jusqu'à cette valeur.

suppress_overlapping_based_on_recent_occlusion_threshold (`float`, *facultatif*, valeur par défaut 0,7) : Seuil pour supprimer les objets superposés en fonction de l'occlusion récente. Les masques superposés dont l'IoU dépasse ce seuil sont supprimés en fonction de celui qui a été le plus récemment occlus.

decrease_trk_keep_alive_for_empty_masklets (`bool`, *facultatif*, valeur par défaut `False`) : Indique s'il faut diminuer le compteur de maintien en vie pour les masklets ayant une surface nulle dans la prédiction SAM2.

fill_hole_area (`int`, *facultatif*, valeur par défaut : 16) : Surface minimale (en pixels) pour combler les trous dans les masques et supprimer les petites taches.

max_num_objects (`int`, *facultatif*, valeur par défaut 10000) : Nombre maximal d'objets à suivre. La valeur par défaut de 10000 désactive en pratique cette limite.

recondition_every_nth_frame (`int`, *facultatif*, valeur par défaut : 16) : Fréquence de la reconditionnement du masque (en images). Définir sur 0 pour désactiver le reconditionnement.

high_conf_thresh (`float`, *facultatif*, valeur par défaut 0,8) : Seuil de confiance élevé pour la reconditionnement. Seules les détections supérieures à ce seuil peuvent reconditionner des tracklets.

high_iou_thresh (`float`, *facultatif*, valeur par défaut 0,8) : Seuil d'IoU élevé pour la reconditionnement. Seules les détections dont l'IoU est supérieur à ce seuil peuvent reconditionner des tracklets.

Ceci est la classe de configuration destinée à stocker la configuration d'un Sam3VideoModel. Elle est utilisée pour instancier un modèle Sam3 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 Sam3VideoConfig, Sam3VideoModel

>>> # Initializing a SAM3 Video configuration with default detector and tracker
>>> configuration = Sam3VideoConfig()

>>> # Changing image size for custom resolution inference (automatically propagates to all nested configs)
>>> configuration.image_size = 560

>>> # Initializing a model from the configuration
>>> model = Sam3VideoModel(configuration)

>>> # Accessing the model configuration
>>> configuration = model.config
>>> detector_config = configuration.detector_config
>>> tracker_config = configuration.tracker_config
```

## Sam3VideoProcessor[[transformers.Sam3VideoProcessor]]

#### transformers.Sam3VideoProcessor[[transformers.Sam3VideoProcessor]]

```python
transformers.Sam3VideoProcessor(image_processor, video_processor, tokenizer, target_size: int | None = None, **kwargs)
```

[Source](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/sam3_video/processing_sam3_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.

tokenizer (`CLIPTokenizer`) : le tokenizer est une entrée obligatoire.

target_size (`int`, *facultatif*) : La taille cible (target_size, target_size) à laquelle l'image sera redimensionnée.

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

[Sam3VideoProcessor](/docs/transformers/v5.23.0/fr/model_doc/sam3_video#transformers.Sam3VideoProcessor) propose toutes les fonctionnalités de [Sam3ImageProcessor](/docs/transformers/v5.23.0/fr/model_doc/sam3#transformers.Sam3ImageProcessor), `video_processor_class` et [CLIPTokenizer](/docs/transformers/v5.23.0/fr/model_doc/clip#transformers.CLIPTokenizer). Consultez [~Sam3ImageProcessor](/docs/transformers/v5.23.0/fr/model_doc/sam3#transformers.Sam3ImageProcessor), `~video_processor_class` et [~CLIPTokenizer](/docs/transformers/v5.23.0/fr/model_doc/clip#transformers.CLIPTokenizer) pour plus d’informations.

#### __appel__[[transformers.Sam3VideoProcessor.__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, 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_video/processing_sam3_video.py#L55)

**Paramètres :**

images (`ImageInput`, *facultatif*) : L'image ou les images à traiter.

segmentation_maps (`ImageInput`, *facultatif*) : Les cartes de segmentation à traiter (facultatif, pour le processeur d'images).

original_sizes (`list[list[float]]`, `torch.Tensor`, *facultatif*) : Les dimensions d'origine des images. Utilisé uniquement lorsque images n'est pas fourni.

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`, *facultatif*) : les cartes de segmentation traitées (si fournies).

#### postprocess_outputs[[transformers.Sam3VideoProcessor.postprocess_outputs]]

```python
postprocess_outputs(inference_session, model_outputs, original_sizes: typing.Union[list[list[float]], torch.Tensor, NoneType] = None)
```

[Source](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/sam3_video/processing_sam3_video.py#L247)

**Paramètres :**

inference_session (`Sam3VideoInferenceSession`) : l'objet de session d'inférence.

model_outputs (`Sam3VideoSegmentationOutput`) : La sortie brute du modèle issue de `Sam3VideoModel.forward()`.

original_sizes (`list[list[float]]` ou `torch.Tensor`, *facultatif*) : Dimensions d'origine des images [hauteur, largeur]. Obligatoire pour l'inférence en flux lorsque video_height/video_width ne sont pas définis dans la session.

**Retourne :** `dict`

Un dictionnaire contenant les clés suivantes :
- **object_ids** (`torch.Tensor` de forme `(num_objects,)`) : identifiants des objets pour chaque objet détecté.
- **scores** (`torch.Tensor` de forme `(num_objects,)`) : Scores de détection pour chaque objet.
- **boxes** (`torch.Tensor` de forme `(num_objects, 4)`) : Boîtes englobantes au format XYXY (top_left_x, top_left_y, bottom_right_x, bottom_right_y).
- **masks** (`torch.Tensor` de forme `(num_objects, height, width)`) : Masques de segmentation binaires pour chaque objet à la résolution vidéo d'origine.
- **prompt_to_obj_ids** (`dict[str, list[int]]`) : Correspondance entre le texte du prompt et la liste des identifiants d'objets détectés par ce prompt.

Post-traitez les sorties du modèle pour obtenir les masques, les boîtes et les scores finaux.

#### init_video_session[[transformers.Sam3VideoProcessor.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_video/processing_sam3_video.py#L133)

**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_text_prompt[[transformers.Sam3VideoProcessor.add_text_prompt]]

```python
add_text_prompt(inference_session: Sam3VideoInferenceSession, text: str | list[str])
```

[Source](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/sam3_video/processing_sam3_video.py#L101)

**Paramètres :**

inference_session (`Sam3VideoInferenceSession`) : la session d'inférence.

text (`str` ou `list[str]`) : Le(s) prompt(s) texte à ajouter.

**Retourne :** `Sam3VideoInferenceSession`

La session d'inférence avec le ou les prompts de texte ajoutés.

Ajouter des invite(s) de texte à la session d'inférence.

## Sam3VideoInferenceSession[[transformers.Sam3VideoInferenceSession]]

#### transformers.Sam3VideoInferenceSession[[transformers.Sam3VideoInferenceSession]]

```python
transformers.Sam3VideoInferenceSession(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_video/modeling_sam3_video.py#L119)

**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.Sam3VideoInferenceSession.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_video/modeling_sam3_video.py#L255)

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

#### add_new_frame[[transformers.Sam3VideoInferenceSession.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_video/modeling_sam3_video.py#L384)

Ajouter un nouveau frame avec un placement automatique des appareils.

#### add_prompt[[transformers.Sam3VideoInferenceSession.add_prompt]]

```python
add_prompt(prompt_text: str)
```

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

Ajoute un prompt texte à la session et renvoie son identifiant unique. Si le prompt existe déjà, renvoie l'identifiant existant.

#### get_frame[[transformers.Sam3VideoInferenceSession.get_frame]]

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

[Source](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/sam3_video/modeling_sam3_video.py#L400)

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

#### get_obj_num[[transformers.Sam3VideoInferenceSession.get_obj_num]]

```python
get_obj_num()
```

[Source](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/sam3_video/modeling_sam3_video.py#L251)

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

#### get_output[[transformers.Sam3VideoInferenceSession.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_video/modeling_sam3_video.py#L357)

**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.Sam3VideoInferenceSession.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_video/modeling_sam3_video.py#L229)

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

#### obj_idx_to_id[[transformers.Sam3VideoInferenceSession.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_video/modeling_sam3_video.py#L247)

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

#### remove_mask_inputs[[transformers.Sam3VideoInferenceSession.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_video/modeling_sam3_video.py#L261)

Supprimer les entrées de masque.

#### remove_object[[transformers.Sam3VideoInferenceSession.remove_object]]

```python
remove_object(obj_id: int, strict: bool = False)
```

[Source](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/sam3_video/modeling_sam3_video.py#L265)

**Paramètres :**

obj_id (`int`) : L'identifiant de l'objet à supprimer.

strict (`bool`, *facultatif*, valeur par défaut `False`) : Indique s'il faut lever une erreur si l'objet n'existe pas.

Supprime un objet de la session d'inférence. Cela supprime l'objet de toutes les images de la vidéo.

#### reset_inference_session[[transformers.Sam3VideoInferenceSession.reset_inference_session]]

```python
reset_inference_session()
```

[Source](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/sam3_video/modeling_sam3_video.py#L416)

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

#### reset_state[[transformers.Sam3VideoInferenceSession.reset_state]]

```python
reset_state()
```

[Source](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/sam3_video/modeling_sam3_video.py#L428)

Réinitialiser l'état de la session d'inférence.

#### reset_tracking_data[[transformers.Sam3VideoInferenceSession.reset_tracking_data]]

```python
reset_tracking_data()
```

[Source](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/sam3_video/modeling_sam3_video.py#L404)

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

#### store_output[[transformers.Sam3VideoInferenceSession.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_video/modeling_sam3_video.py#L320)

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

## Sam3VideoSegmentationOutput[[transformers.Sam3VideoSegmentationOutput]]

#### transformers.Sam3VideoSegmentationOutput[[transformers.Sam3VideoSegmentationOutput]]

```python
transformers.Sam3VideoSegmentationOutput(object_ids: list[int] | None = None, obj_id_to_mask: dict[int, torch.Tensor] | None = None, obj_id_to_score: dict[int, float] | None = None, obj_id_to_tracker_score: dict[int, float] | None = None, removed_obj_ids: set[int] | None = None, suppressed_obj_ids: set[int] | None = None, frame_idx: int | None = None)
```

[Source](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/sam3_video/modeling_sam3_video.py#L462)

**Paramètres :**

object_ids (`list[int]`, *facultatif*) : Liste des identifiants d'objets suivis dans l'image courante.

obj_id_to_mask (`dict[int, torch.Tensor]`, *facultatif*) : Dictionnaire associant les identifiants d'objets à leurs masques prédits en basse résolution. Chaque masque a la forme `(1, H_low, W_low)`.

obj_id_to_score (`dict[int, float]`, *facultatif*) : Dictionnaire associant les identifiants d'objets à leurs scores de détection.

obj_id_to_tracker_score (`dict[int, float]`, *facultatif*) : Dictionnaire associant les identifiants d'objets à leurs scores de suivi pour l'image courante.

removed_obj_ids (`set[int]`, *facultatif*) : Ensemble d'identifiants d'objets qui ont été supprimés (par exemple, via des heuristiques de hotstart).

suppressed_obj_ids (`set[int]`, *facultatif*) : Ensemble d'identifiants d'objets qui ont été supprimés dans la frame actuelle.

frame_idx (`int`, *facultatif*) : L'index de la frame de la vidéo.

Classe de base pour la sortie du modèle Sam3Video.

## Sam3VideoModel[[transformers.Sam3VideoModel]]

#### transformers.Sam3VideoModel[[transformers.Sam3VideoModel]]

```python
transformers.Sam3VideoModel(config: Sam3VideoConfig)
```

[Source](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/sam3_video/modeling_sam3_video.py#L507)

**Paramètres :**

config ([Sam3VideoConfig](/docs/transformers/v5.23.0/fr/model_doc/sam3_video#transformers.Sam3VideoConfig)) : 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.

Le modèle Sam3 Video 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.Sam3VideoModel.forward]]

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

[Source](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/sam3_video/modeling_sam3_video.py#L1693)

**Paramètres :**

inference_session (`~models.sam3_video.modeling_sam3_video.Sam3VideoInferenceSession`) : 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.

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

#### propagate_in_video_iterator[[transformers.Sam3VideoModel.propagate_in_video_iterator]]

```python
propagate_in_video_iterator(inference_session: Sam3VideoInferenceSession, start_frame_idx: int = 0, 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_video/modeling_sam3_video.py#L1784)

**Paramètres :**

inference_session (`~models.sam3_video.modeling_sam3_video.Sam3VideoInferenceSession`) : l'objet de session d'inférence vidéo.

start_frame_idx (`int`, *facultatif*, valeur par défaut `0`) : Index de la frame de départ pour la propagation.

max_frame_num_to_track (`int`, *facultatif*) : Nombre maximal de frames à suivre. Si non fourni, toutes les frames de la vidéo seront suivies.

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 :** [Sam3VideoSegmentationOutput](/docs/transformers/v5.23.0/fr/model_doc/sam3_video#transformers.Sam3VideoSegmentationOutput) ou `tuple(torch.Tensor)`

Un [Sam3VideoSegmentationOutput](/docs/transformers/v5.23.0/fr/model_doc/sam3_video#transformers.Sam3VideoSegmentationOutput) 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 ([Sam3VideoConfig](/docs/transformers/v5.23.0/fr/model_doc/sam3_video#transformers.Sam3VideoConfig)) et les entrées.

Propage les invites pour obtenir les résultats de localisation sur l’ensemble de la vidéo. Utilisé lors de l’initialisation d’une session d’inférence avec une vidéo complète. Produit un Sam3VideoSegmentationOutput pour chaque image.

- **object_ids** (`list[int]`, *facultatif*) -- Liste des identifiants d'objets suivis dans l'image courante.
- **obj_id_to_mask** (`dict[int, torch.Tensor]`, *facultatif*) -- Dictionnaire associant les identifiants d'objets à leurs masques basse résolution prédits. Chaque masque a la forme `(1, H_low, W_low)`.
- **obj_id_to_score** (`dict[int, float]`, *facultatif*) -- Dictionnaire associant les identifiants d'objets à leurs scores de détection.
- **obj_id_to_tracker_score** (`dict[int, float]`, *facultatif*) -- Dictionnaire associant les identifiants d'objets à leurs scores de suivi pour l'image courante.
- **removed_obj_ids** (`set[int]`, *facultatif*) -- Ensemble des identifiants d'objets qui ont été supprimés (par exemple, via des heuristiques de démarrage à chaud).
- **suppressed_obj_ids** (`set[int]`, *facultatif*) -- Ensemble des identifiants d'objets qui ont été supprimés dans la frame actuelle.
- **frame_idx** (`int`, *facultatif*) -- L'index de la frame de la vidéo.