Hugging Face's logo

Transformers documentation

SAM3 Tracker

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).
Hugging Face's logo
Join the Hugging Face community

and get access to the augmented documentation experience

to get started

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

SAM3 Tracker

SDPA FlashAttention

Aperçu

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

Sam3Tracker effectue une segmentation visuelle promptable (PVS) sur des images. La PVS utilise des prompts visuels interactifs (points, boîtes, masques) ou des entrées textuelles pour segmenter une instance d'objet spécifique par prompt. C'est la tâche sur laquelle SAM 1 et SAM 2 se sont concentrés, et SAM 3 l'améliore.

Sam3Tracker est une version mise à jour de SAM2 (Segment Anything Model 2) qui conserve la même API tout en offrant des performances et des capacités améliorées.

L'abstract de l'article est le suivant :

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

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

Exemple d'utilisation

Génération automatique de masques avec Pipeline

Sam3Tracker peut être utilisé pour la génération automatique de masques afin de segmenter tous les objets d'une image à l'aide du pipeline mask-generation :

from transformers import pipeline


generator = pipeline("mask-generation", model="facebook/sam3", device=0)
image_url = "https://huggingface.co/datasets/hf-internal-testing/sam2-fixtures/resolve/main/truck.jpg"
outputs = generator(image_url, points_per_batch=64)

len(outputs["masks"])  # Number of masks generated
39

Segmentation d’images de base

Clic en un seul point

Vous pouvez segmenter des objets en effectuant un simple clic sur l'objet que vous souhaitez segmenter :

from transformers import Sam3TrackerProcessor, Sam3TrackerModel
import torch
from PIL import Image
import requests


model = Sam3TrackerModel.from_pretrained("facebook/sam3", device_map="auto")
processor = Sam3TrackerProcessor.from_pretrained("facebook/sam3")

image_url = "https://huggingface.co/datasets/hf-internal-testing/sam2-fixtures/resolve/main/truck.jpg"
raw_image = Image.open(requests.get(image_url, stream=True).raw).convert("RGB")

input_points = [[[[500, 375]]]]  # Single point click, 4 dimensions (image_dim, object_dim, point_per_object_dim, coordinates)
input_labels = [[[1]]]  # 1 for positive click, 0 for negative click, 3 dimensions (image_dim, object_dim, point_label)

inputs = processor(images=raw_image, input_points=input_points, input_labels=input_labels, return_tensors="pt").to(model.device)

with torch.no_grad():
    outputs = model(**inputs)

masks = processor.post_process_masks(outputs.pred_masks.cpu(), inputs["original_sizes"])[0]

# The model outputs multiple mask predictions ranked by quality score
print(f"Generated {masks.shape[1]} masks with shape {masks.shape}")
Generated 3 masks with shape torch.Size([1, 3, 1500, 2250])

Plusieurs points à affiner

Vous pouvez fournir plusieurs points pour affiner la segmentation :

# Add both positive and negative points to refine the mask
input_points = [[[[500, 375], [1125, 625]]]]  # Multiple points for refinement
input_labels = [[[1, 1]]]  # Both positive clicks

inputs = processor(images=raw_image, input_points=input_points, input_labels=input_labels, return_tensors="pt").to(model.device)

with torch.no_grad():
    outputs = model(**inputs)

masks = processor.post_process_masks(outputs.pred_masks.cpu(), inputs["original_sizes"])[0]

Entrée de boîte englobante

Sam3Tracker prend également en charge les entrées de type boîte englobante pour la segmentation :

# Define bounding box as [x_min, y_min, x_max, y_max]
input_boxes = [[[75, 275, 1725, 850]]]

inputs = processor(images=raw_image, input_boxes=input_boxes, return_tensors="pt").to(model.device)

with torch.no_grad():
    outputs = model(**inputs)

masks = processor.post_process_masks(outputs.pred_masks.cpu(), inputs["original_sizes"])[0]

Segmentation de plusieurs objets

Vous pouvez segmenter plusieurs objets simultanément :

# Define points for two different objects
input_points = [[[[500, 375]], [[650, 750]]]]  # Points for two objects in same image
input_labels = [[[1], [1]]]  # Positive clicks for both objects

inputs = processor(images=raw_image, input_points=input_points, input_labels=input_labels, return_tensors="pt").to(model.device)

with torch.no_grad():
    outputs = model(**inputs, multimask_output=False)

# Each object gets its own mask
masks = processor.post_process_masks(outputs.pred_masks.cpu(), inputs["original_sizes"])[0]
print(f"Generated masks for {masks.shape[0]} objects")
Generated masks for 2 objects

Inférence par lots

Images par lots

Traitez plusieurs images simultanément pour une efficacité accrue :

from transformers import Sam3TrackerProcessor, Sam3TrackerModel
import torch
from PIL import Image
import requests


model = Sam3TrackerModel.from_pretrained("facebook/sam3", device_map="auto")
processor = Sam3TrackerProcessor.from_pretrained("facebook/sam3")

# Load multiple images
image_urls = [
    "https://huggingface.co/datasets/hf-internal-testing/sam2-fixtures/resolve/main/truck.jpg",
    "https://huggingface.co/datasets/hf-internal-testing/transformers-synthetic-assets/resolve/main/images/dog_sam.png"
]
raw_images = [Image.open(requests.get(url, stream=True).raw).convert("RGB") for url in image_urls]

# Single point per image
input_points = [[[[500, 375]]], [[[770, 200]]]]  # One point for each image
input_labels = [[[1]], [[1]]]  # Positive clicks for both images

inputs = processor(images=raw_images, input_points=input_points, input_labels=input_labels, return_tensors="pt").to(model.device)

with torch.no_grad():
    outputs = model(**inputs, multimask_output=False)

# Post-process masks for each image
all_masks = processor.post_process_masks(outputs.pred_masks.cpu(), inputs["original_sizes"])
print(f"Processed {len(all_masks)} images, each with {all_masks[0].shape[0]} objects")
Processed 2 images, each with 1 objects

Objets par lot par image

Segmenter plusieurs objets dans chaque image à l'aide d'une inférence par lot :

# Multiple objects per image - different numbers of objects per image
input_points = [
    [[[500, 375]], [[650, 750]]],  # Truck image: 2 objects
    [[[770, 200]]]  # Dog image: 1 object
]
input_labels = [
    [[1], [1]],  # Truck image: positive clicks for both objects
    [[1]]  # Dog image: positive click for the object
]

inputs = processor(images=raw_images, input_points=input_points, input_labels=input_labels, return_tensors="pt").to(model.device)

with torch.no_grad():
    outputs = model(**inputs, multimask_output=False)

all_masks = processor.post_process_masks(outputs.pred_masks.cpu(), inputs["original_sizes"])

Images par lots avec des objets par lots et plusieurs points

Gérer des scénarios de lot complexes avec plusieurs points par objet :

# Add groceries image for more complex example
groceries_url = "https://huggingface.co/datasets/hf-internal-testing/sam2-fixtures/resolve/main/groceries.jpg"
groceries_image = Image.open(requests.get(groceries_url, stream=True).raw).convert("RGB")
raw_images = [raw_images[0], groceries_image]  # Use truck and groceries images

# Complex batching: multiple images, multiple objects, multiple points per object
input_points = [
    [[[500, 375]], [[650, 750]]],  # Truck image: 2 objects with 1 point each
    [[[400, 300]], [[630, 300], [550, 300]]]  # Groceries image: obj1 has 1 point, obj2 has 2 points
]
input_labels = [
    [[1], [1]],  # Truck image: positive clicks
    [[1], [1, 1]]  # Groceries image: positive clicks for refinement
]

inputs = processor(images=raw_images, input_points=input_points, input_labels=input_labels, return_tensors="pt").to(model.device)

with torch.no_grad():
    outputs = model(**inputs, multimask_output=False)

all_masks = processor.post_process_masks(outputs.pred_masks.cpu(), inputs["original_sizes"])

Boîtes englobantes par lots

Traiter plusieurs images avec des entrées de boîtes englobantes :

# Multiple bounding boxes per image (using truck and groceries images)
input_boxes = [
    [[75, 275, 1725, 850], [425, 600, 700, 875], [1375, 550, 1650, 800], [1240, 675, 1400, 750]],  # Truck image: 4 boxes
    [[450, 170, 520, 350], [350, 190, 450, 350], [500, 170, 580, 350], [580, 170, 640, 350]]  # Groceries image: 4 boxes
]

# Update images for this example
raw_images = [raw_images[0], groceries_image]  # truck and groceries

inputs = processor(images=raw_images, input_boxes=input_boxes, return_tensors="pt").to(model.device)

with torch.no_grad():
    outputs = model(**inputs, multimask_output=False)

all_masks = processor.post_process_masks(outputs.pred_masks.cpu(), inputs["original_sizes"])
print(f"Processed {len(input_boxes)} images with {len(input_boxes[0])} and {len(input_boxes[1])} boxes respectively")
Processed 2 images with 4 and 4 boxes respectively

Utilisation des masques précédents en tant qu'entrée

Sam3Tracker peut utiliser les masques des prédictions précédentes comme entrée pour affiner la segmentation :

# Get initial segmentation
input_points = [[[[500, 375]]]]
input_labels = [[[1]]]
inputs = processor(images=raw_image, input_points=input_points, input_labels=input_labels, return_tensors="pt").to(model.device)

with torch.no_grad():
    outputs = model(**inputs)

# Use the best mask as input for refinement
mask_input = outputs.pred_masks[:, :, torch.argmax(outputs.iou_scores.squeeze())]

# Add additional points with the mask input
new_input_points = [[[[500, 375], [450, 300]]]]
new_input_labels = [[[1, 1]]]
inputs = processor(
    input_points=new_input_points,
    input_labels=new_input_labels,
    original_sizes=inputs["original_sizes"],
    return_tensors="pt",
).to(model.device)

with torch.no_grad():
    refined_outputs = model(
        **inputs,
        input_masks=mask_input,
        image_embeddings=outputs.image_embeddings,
        multimask_output=False,
    )

Sam3TrackerConfig

classe transformers.Sam3TrackerConfig

< >

( transformers_version: str | None = Nonearchitectures: list[str] | None = Noneoutput_hidden_states: bool | None = Falsereturn_dict: bool | None = Truedtype: str | torch.dtype | None = Nonechunk_size_feed_forward: int = 0is_encoder_decoder: bool = Falseid2label: dict[int, str] | dict[str, str] | None = Nonelabel2id: dict[str, int] | dict[str, str] | None = Noneproblem_type: Literal['regression', 'single_label_classification', 'multi_label_classification'] | None = Nonevision_config: dict | transformers.configuration_utils.PreTrainedConfig | None = Noneprompt_encoder_config: dict | transformers.configuration_utils.PreTrainedConfig | None = Nonemask_decoder_config: dict | transformers.configuration_utils.PreTrainedConfig | None = Noneinitializer_range: float = 0.02 )

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, Sam3TrackerPromptEncoderConfig], facultatif) — Dictionnaire des options de configuration utilisées pour initialiser Sam3TrackerPromptEncoderConfig.
  • mask_decoder_config (Union[dict, Sam3TrackerMaskDecoderConfig], facultatif) — Dictionnaire des options de configuration utilisées pour initialiser Sam3TrackerMaskDecoderConfig.
  • initializer_range (float, facultatif, par défaut 0.02) — L'écart-type de la truncated_normal_initializer utilisé pour initialiser toutes les matrices de poids.

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

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

Exemple :

>>> from transformers import (
...     Sam3TrackerVisionConfig,
...     Sam3TrackerPromptEncoderConfig,
...     Sam3TrackerMaskDecoderConfig,
...     Sam3TrackerModel,
... )

>>> # Initializing a Sam3TrackerConfig with `"facebook/sam3_tracker.1_hiera_tiny"` style configuration
>>> configuration = Sam3TrackerConfig()

>>> # Initializing a Sam3TrackerModel (with random weights) from the `"facebook/sam3_tracker.1_hiera_tiny"` style configuration
>>> model = Sam3TrackerModel(configuration)

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

>>> # We can also initialize a Sam3TrackerConfig from a Sam3TrackerVisionConfig, Sam3TrackerPromptEncoderConfig, and Sam3TrackerMaskDecoderConfig
>>> # Initializing SAM3_TRACKER vision encoder, memory attention, and memory encoder configurations
>>> vision_config = Sam3TrackerVisionConfig()
>>> prompt_encoder_config = Sam3TrackerPromptEncoderConfig()
>>> mask_decoder_config = Sam3TrackerMaskDecoderConfig()

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

Sam3TrackerPromptEncoderConfig

classe transformers.Sam3TrackerPromptEncoderConfig

< >

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

Paramètres

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

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

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

Sam3TrackerMaskDecoderConfig

classe transformers.Sam3TrackerMaskDecoderConfig

< >

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

Paramètres

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

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

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

Sam3TrackerProcessor

classe transformers.Sam3TrackerProcessor

< >

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

Paramètres

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

Construit un Sam3TrackerProcessor qui encapsule un processeur d’image en un seul processeur.

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

__call__

< >

( images: typing.Union[ForwardRef('PIL.Image.Image'), numpy.ndarray, ForwardRef('torch.Tensor'), list['PIL.Image.Image'], list[numpy.ndarray], list['torch.Tensor'], NoneType] = Nonesegmentation_maps: typing.Union[ForwardRef('PIL.Image.Image'), numpy.ndarray, ForwardRef('torch.Tensor'), list['PIL.Image.Image'], list[numpy.ndarray], list['torch.Tensor'], NoneType] = Noneinput_points: typing.Union[list[list[list[list[float]]]], torch.Tensor, NoneType] = Noneinput_labels: typing.Union[list[list[list[int]]], torch.Tensor, NoneType] = Noneinput_boxes: typing.Union[list[list[list[float]]], torch.Tensor, NoneType] = Noneoriginal_sizes: typing.Union[list[list[float]], torch.Tensor, NoneType] = Nonereturn_tensors: str | transformers.utils.generic.TensorType | None = None**kwargs ) → A BatchEncoding with the following fields

Paramètres

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

Retourne

Un BatchEncoding avec les champs suivants

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

post_process_masks

< >

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

Paramètres

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

Retourne

(torch.Tensor)

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

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

Sam3TrackerModel

classe transformers.Sam3TrackerModel

< >

( config: Sam3TrackerConfig )

Paramètres

  • config (Sam3TrackerConfig) — Classe de configuration du modèle contenant tous les paramètres du modèle. L’initialisation à partir d’un fichier de configuration ne charge pas les poids associés au modèle, uniquement la configuration. Consultez la méthode from_pretrained() pour charger les poids du modèle.

Segment Anything Model 2 (SAM 2) pour générer des masques de segmentation, à partir d'une image d'entrée et de points et étiquettes, boîtes ou masques d'entrée.

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

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

forward

< >

( pixel_values: typing.Optional[torch.Tensor] = Noneinput_points: typing.Optional[torch.Tensor] = Noneinput_labels: typing.Optional[torch.LongTensor] = Noneinput_boxes: typing.Optional[torch.Tensor] = Noneinput_masks: typing.Optional[torch.LongTensor] = Noneimage_embeddings: typing.Optional[torch.Tensor] = Nonemultimask_output: bool = Trueattention_similarity: typing.Optional[torch.Tensor] = Nonetarget_embedding: typing.Optional[torch.Tensor] = None**kwargs: *<class 'transformers.utils.generic.TransformersKwargs'> ) → Sam3TrackerImageSegmentationOutput or tuple(torch.Tensor)

Paramètres

  • pixel_values (torch.Tensor de forme (batch_size, num_channels, image_size, image_size), facultatif) — Les tenseurs correspondant aux images d’entrée. Les valeurs de pixels peuvent être obtenues à l’aide de Sam3ImageProcessor. Voir Sam3ImageProcessor.call() pour plus de détails (Sam3TrackerProcessor utilise Sam3ImageProcessor pour le traitement des images).
  • input_points (torch.Tensor de forme (batch_size, num_points, 2)) — Points spatiaux 2D en entrée, utilisés par l’encodeur de prompt pour encoder le prompt. Produit généralement des résultats nettement meilleurs. Les points peuvent être obtenus en transmettant une liste de listes de listes au processeur, qui créera les tenseurs torch correspondants de dimension 4. La première dimension correspond à la taille du lot d’images, la deuxième à la taille du lot de points (c’est-à-dire le nombre de masques de segmentation que le modèle doit prédire par point d’entrée), la troisième au nombre de points par masque de segmentation (il est possible de transmettre plusieurs points pour un seul masque), et la dernière aux coordonnées x (verticale) et y (horizontale) du point. Si un nombre différent de points est transmis pour chaque image ou pour chaque masque, le processeur créera des points « PAD » correspondant à la coordonnée (0, 0), et le calcul de l’embedding sera ignoré pour ces points à l’aide des étiquettes.
  • input_labels (torch.LongTensor de forme (batch_size, point_batch_size, num_points)) — Étiquettes d'entrée pour les points, utilisées par l'encodeur de prompt pour encoder le prompt. Selon l'implémentation officielle, il existe 3 types d'étiquettes
    • 1 : le point est un point qui contient l'objet d'intérêt
    • 0 : le point est un point qui ne contient pas l'objet d'intérêt
    • -1 : le point correspond à l'arrière-plan

    Nous avons ajouté l'étiquette :

    • -10 : le point est un point de bourrage, il doit donc être ignoré par l'encodeur de prompt

    Les étiquettes de bourrage doivent être effectuées automatiquement par le processeur.

  • input_boxes (torch.Tensor de forme (batch_size, num_boxes, 4)) — Boîtes d'entrée pour les points, utilisées par l'encodeur de prompt pour encoder le prompt. Elles produisent généralement des masques générés bien meilleurs. Les boîtes peuvent être obtenues en passant une liste de listes de listes au processeur, qui génère un torch tenseur, où chaque dimension correspond respectivement à la taille du lot d'images, au nombre de boîtes par image et aux coordonnées du point en haut à gauche et du point en bas à droite de la boîte. Dans l'ordre (x1, y1, x2, y2):
    • x1 : la coordonnée x du point en haut à gauche de la boîte d'entrée
    • y1 : la coordonnée y du point en haut à gauche de la boîte d'entrée
    • x2 : la coordonnée x du point en bas à droite de la boîte d'entrée
    • y2 : la coordonnée y du point en bas à droite de la boîte d'entrée
  • input_masks (torch.Tensor de forme (batch_size, image_size, image_size)) — Le modèle SAM accepte également des masques de segmentation en entrée. Le masque sera intégré par l’encodeur de prompt pour générer un embedding correspondant, qui sera ensuite transmis au décodeur de masque. Ces masques doivent être fournis manuellement par l’utilisateur et doivent être de forme (batch_size, image_size, image_size).
  • image_embeddings (torch.Tensor de forme (batch_size, output_channels, window_size, window_size)) — Embeddings d’image, utilisés par le décodeur de masque pour générer les masques et les scores iou. Pour un calcul plus efficace en mémoire, les utilisateurs peuvent d’abord récupérer les embeddings d’image à l’aide de la méthode get_image_embeddings, puis les transmettre à la méthode forward au lieu de transmettre les pixel_values.
  • multimask_output (bool, facultatif) — Dans l’implémentation et l’article originaux, le modèle produit toujours 3 masques par image (ou par point / par boîte englobante le cas échéant). Il est toutefois possible de n’afficher qu’un seul masque, correspondant au meilleur masque, en spécifiant multimask_output=False.
  • attention_similarity (torch.Tensor, facultatif) — Tenseur de similarité d’attention, à fournir au décodeur de masque pour une attention guidée par la cible lorsque le modèle est utilisé pour la personnalisation, comme introduit dans PerSAM.
  • target_embedding (torch.Tensor, facultatif) — Embedding du concept cible, à fournir au décodeur de masque pour le prompting sémantique de la cible dans le cas où le modèle est utilisé pour la personnalisation, comme introduit dans PerSAM.

Retourne

Sam3TrackerImageSegmentationOutput ou tuple(torch.Tensor)

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

La méthode forward du modèle Sam3TrackerModel redéfinit la méthode spéciale __call__.

Bien que la recette de la passe avant doive être définie dans cette fonction, il faut ensuite appeler l'instance Module plutôt que celle-ci, car la première gère l'exécution des étapes de prétraitement et de post-traitement, tandis que la seconde les ignore silencieusement.

  • iou_scores (torch.Tensor de forme (batch_size, point_batch_size, num_masks)) — Les scores d'Intersection sur Union (IoU) des masques prédits.
  • pred_masks (torch.Tensor de forme (batch_size, point_batch_size, num_masks, height, width)) — Les masques basse résolution prédits. C'est un alias de low_res_masks. Ces masques doivent être post-traités par le processeur pour être ramenés à la taille de l'image d'origine.
  • object_score_logits (torch.Tensor de forme (batch_size, point_batch_size, 1)) — Logits du score d'objet, indiquant si un objet est présent.
  • image_embeddings (tuple(torch.Tensor)) — Les caractéristiques issues du FPN, utilisées par le décodeur de masque. Il s’agit d’un tuple de torch.Tensor où chaque tenseur a la forme (batch_size, channels, height, width).
  • vision_hidden_states (tuple(torch.Tensor), facultatif, renvoyé lorsque output_hidden_states=True) — Tuple de torch.Tensor (un pour la sortie de chaque étape) de forme (batch_size, height, width, hidden_size). États cachés du modèle de vision à la sortie de chaque étape.
  • vision_attentions (tuple(torch.Tensor), facultatif, renvoyé lorsque output_attentions=True) — Tuple de torch.Tensor (un par couche) de forme (batch_size, num_heads, sequence_length, sequence_length). Poids d'attention du modèle de vision.
  • mask_decoder_attentions (tuple(torch.Tensor), facultatif, renvoyé lorsque output_attentions=True) — Tuple de torch.Tensor (un par couche) de forme (batch_size, num_heads, sequence_length, sequence_length). Poids d'attention du décodeur de masque.

Exemple :

>>> from PIL import Image
>>> from huggingface_hub.utils import httpx
>>> from io import BytesIO
>>> from transformers import AutoModel, AutoProcessor

>>> model = AutoModel.from_pretrained("danelcsb/sam3_tracker.1_hiera_tiny")
>>> processor = AutoProcessor.from_pretrained("danelcsb/sam3_tracker.1_hiera_tiny")

>>> url = "https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/transformers/model_doc/sam-car.png"
>>> with httpx.stream("GET", url) as response:
...     raw_image = Image.open(BytesIO(response.read())).convert("RGB")
>>> input_points = [[[400, 650]]]  # 2D location of a window on the car
>>> inputs = processor(images=raw_image, input_points=input_points, return_tensors="pt")

>>> # Get segmentation mask
>>> outputs = model(**inputs)

>>> # Postprocess masks
>>> masks = processor.post_process_masks(
...     outputs.pred_masks, inputs["original_sizes"]
... )

get_image_features

< >

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

Paramètres

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

Retourne

Sam3TrackerVisionEncoderOutput ou tuple(torch.Tensor)

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

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

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

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

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

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

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

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

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

Exemple :

Sam3TrackerPreTrainedModel

classe transformers.Sam3TrackerPreTrainedModel

< >

( config: PreTrainedConfig*inputs**kwargs )

Paramètres

  • config (PreTrainedConfig) — Classe de configuration du modèle contenant tous les paramètres du modèle. L’initialisation à partir d’un fichier de configuration ne charge pas les poids associés au modèle, uniquement la configuration. Consultez la méthode from_pretrained() pour charger les poids du modèle.

Segment Anything Model 3 (SAM 3) pour générer des masques de segmentation, à partir d'une image d'entrée et de points et étiquettes, boîtes ou masques en entrée.

forward

( *args**kwargs )

Valeur factice pour un chemin pointé (par exemple torch.float32) : les chaînes d’accès aux attributs et les appels se comportent comme des décorateurs de pass-through, repr est le chemin pointé, et son utilisation comme classe de base substitue une base type ordinaire (PEP 560 __mro_entries__), de sorte que les vraies sous-classes conservent un métaclasse normal et que inspect.signature lit leur __init__ réel plutôt que celui d’une valeur factice.

Update on GitHub

←SAM2 Sapiens2→