Transformers documentation

SAM3 Vidéo

Transformers

You are viewing main version, which requires installation from source. If you'd like regular pip install, checkout the latest stable version (v5.22.1).

Join the Hugging Face community

and get access to the augmented documentation experience

Collaborate on models, datasets and Spaces

Faster examples with accelerated inference

Switch between documentation themes

to get started

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

SAM3 Vidéo

Aperçu

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

SAM3 Video effectue le segmentation de concepts promptables (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 de la vidéo.

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 promptable (PCS) prend de tels prompts en entrée et renvoie des masques de segmentation et des identités uniques pour toutes les instances d’objets correspondantes. Pour faire progresser la PCS, nous avons construit un moteur de données scalable qui produit un jeu de données de haute qualité avec 4M de libellés de concepts uniques, incluant des négatifs difficiles, sur des images et des vidéos. Notre modèle se compose d’un détecteur au niveau de l’image et d’un suiveur vidéo basé sur la mémoire qui partagent un seul backbone. La reconnaissance et la localisation sont découplées par une tête de présence, ce qui améliore la précision de la détection. SAM 3 double la précision des systèmes existants en PCS sur images et vidéos, et améliore les capacités précédentes de SAM sur les tâches de segmentation visuelle. Nous open source SAM 3 ainsi que notre nouveau benchmark Segment Anything with Concepts (SA-Co) pour la segmentation de concepts promptable.

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

Exemple d'utilisation

Segmentation et suivi vidéo

Inférence vidéo préchargée

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

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 :

# 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

⚠️ **Remarque 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 dupliqués, 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 dupliquées par rapport à l'inférence sur une vidéo préchargée. Pour obtenir les meilleurs résultats, utilisez l'inférence sur une 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 :

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

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

Transformers

SAM3 Vidéo

Aperçu

Exemple d'utilisation

Segmentation et suivi vidéo

Inférence vidéo préchargée

Inférence vidéo en streaming

Inférence à résolution personnalisée

Sam3VideoConfig

classe transformers.Sam3VideoConfig

Sam3VideoProcessor

classe transformers.Sam3VideoProcessor

__call__

postprocess_outputs

init_video_session

add_text_prompt

Sam3VideoInferenceSession

classe transformers.Sam3VideoInferenceSession

add_mask_inputs

add_new_frame

add_prompt

get_frame

get_obj_num

get_output

obj_id_to_idx

obj_idx_to_id

remove_mask_inputs

remove_object

reset_inference_session

reset_state

reset_tracking_data

store_output

Sam3VideoSegmentationOutput

classe transformers.Sam3VideoSegmentationOutput

Sam3VideoModel

classe transformers.Sam3VideoModel

forward

propagate_in_video_iterator

call