# SAM3 Tracker

    
        
        
    

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

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

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

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

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

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

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

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

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

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

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

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

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

#### transformers.Sam3TrackerConfig[[transformers.Sam3TrackerConfig]]

```python
transformers.Sam3TrackerConfig(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)
```

[Source](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/sam3_tracker/configuration_sam3_tracker.py#L96)

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

mask_decoder_config (Union[`dict`, `Sam3TrackerMaskDecoderConfig`], *facultatif*) : Dictionnaire des options de configuration utilisées pour initialiser [Sam3TrackerMaskDecoderConfig](/docs/transformers/v5.23.0/fr/model_doc/sam3_tracker#transformers.Sam3TrackerMaskDecoderConfig).

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

Ceci est 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](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 (
...     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[[transformers.Sam3TrackerPromptEncoderConfig]]

#### transformers.Sam3TrackerPromptEncoderConfig[[transformers.Sam3TrackerPromptEncoderConfig]]

```python
transformers.Sam3TrackerPromptEncoderConfig(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/configuration_sam3_tracker.py#L31)

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

Ceci est 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](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.

## Sam3TrackerMaskDecoderConfig[[transformers.Sam3TrackerMaskDecoderConfig]]

#### transformers.Sam3TrackerMaskDecoderConfig[[transformers.Sam3TrackerMaskDecoderConfig]]

```python
transformers.Sam3TrackerMaskDecoderConfig(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/configuration_sam3_tracker.py#L57)

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

Ceci est 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](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.

## Sam3TrackerProcessor[[transformers.Sam3TrackerProcessor]]

#### transformers.Sam3TrackerProcessor[[transformers.Sam3TrackerProcessor]]

```python
transformers.Sam3TrackerProcessor(image_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/processing_sam3_tracker.py#L36)

**Paramètres :**

image_processor (`Sam3ImageProcessor`) : le processeur d'images 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 Sam3TrackerProcessor qui encapsule un processeur d’image en un seul processeur.

[Sam3TrackerProcessor](/docs/transformers/v5.23.0/fr/model_doc/sam3_tracker#transformers.Sam3TrackerProcessor) propose toutes les fonctionnalités de [Sam3ImageProcessor](/docs/transformers/v5.23.0/fr/model_doc/sam3#transformers.Sam3ImageProcessor). Consultez [~Sam3ImageProcessor](/docs/transformers/v5.23.0/fr/model_doc/sam3#transformers.Sam3ImageProcessor) pour plus d’informations.

#### __appel__[[transformers.Sam3TrackerProcessor.__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/processing_sam3_tracker.py#L52)

**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.Sam3TrackerProcessor.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/processing_sam3_tracker.py#L458)

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

## Sam3TrackerModel[[transformers.Sam3TrackerModel]]

#### transformers.Sam3TrackerModel[[transformers.Sam3TrackerModel]]

```python
transformers.Sam3TrackerModel(config: Sam3TrackerConfig)
```

[Source](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/sam3_tracker/modeling_sam3_tracker.py#L772)

**Paramètres :**

config ([Sam3TrackerConfig](/docs/transformers/v5.23.0/fr/model_doc/sam3_tracker#transformers.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()](/docs/transformers/v5.23.0/fr/main_classes/model#transformers.PreTrainedModel.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 d'étiquettes, de boîtes ou de masques en entrée.

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.Sam3TrackerModel.forward]]

```python
forward(pixel_values: typing.Optional[torch.Tensor] = None, input_points: typing.Optional[torch.Tensor] = None, input_labels: typing.Optional[torch.LongTensor] = None, input_boxes: typing.Optional[torch.Tensor] = None, input_masks: typing.Optional[torch.LongTensor] = None, image_embeddings: typing.Optional[torch.Tensor] = None, multimask_output: bool = True, attention_similarity: typing.Optional[torch.Tensor] = None, target_embedding: typing.Optional[torch.Tensor] = None, **kwargs: *<class 'transformers.utils.generic.TransformersKwargs'>)
```

[Source](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/sam3_tracker/modeling_sam3_tracker.py#L886)

**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](/docs/transformers/v5.23.0/fr/model_doc/sam3#transformers.Sam3ImageProcessor). Voir [Sam3ImageProcessor.__call__()](/docs/transformers/v5.23.0/fr/model_doc/molmo2#transformers.Molmo2ImageProcessor.__call__) pour plus de détails ([Sam3TrackerProcessor](/docs/transformers/v5.23.0/fr/model_doc/sam3_tracker#transformers.Sam3TrackerProcessor) utilise [Sam3ImageProcessor](/docs/transformers/v5.23.0/fr/model_doc/sam3#transformers.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 contient l'objet d'intérêt ; `0` : le point 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 (padding) et doit donc être ignoré par l'encodeur de prompt. Les étiquettes de bourrage doivent être géré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. Produit généralement des masques générés nettement meilleurs. Les boîtes peuvent être obtenues en transmettant une liste de listes de listes au processeur, qui générera un tenseur `torch`, chaque dimension correspondant 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’en produire qu’un seul, correspondant au masque « optimal », 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](https://huggingface.co/papers/2305.03048).

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](https://huggingface.co/papers/2305.03048).

**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 selon la configuration ([Sam3TrackerConfig](/docs/transformers/v5.23.0/fr/model_doc/sam3_tracker#transformers.Sam3TrackerConfig)) et les entrées.

La méthode forward du modèle [Sam3TrackerModel](/docs/transformers/v5.23.0/fr/model_doc/sam3_tracker#transformers.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 d'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 :

```python
>>> 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[[transformers.Sam3TrackerModel.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/modeling_sam3_tracker.py#L1064)

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

Exemple :

```python
```

## Sam3TrackerPreTrainedModel[[transformers.Sam3TrackerPreTrainedModel]]

#### transformers.Sam3TrackerPreTrainedModel[[transformers.Sam3TrackerPreTrainedModel]]

```python
transformers.Sam3TrackerPreTrainedModel(config: PreTrainedConfig, *inputs, **kwargs)
```

[Source](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/sam3_tracker/modeling_sam3_tracker.py#L117)

**Paramètres :**

config ([PreTrainedConfig](/docs/transformers/v5.23.0/fr/main_classes/configuration#transformers.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()](/docs/transformers/v5.23.0/fr/main_classes/model#transformers.PreTrainedModel.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, étiquettes, boîtes ou masques d'entrée.

#### forward[[transformers.Sam3TrackerPreTrainedModel.forward]]

```python
forward(*args, **kwargs)
```

Une valeur factice pour un chemin pointé (par ex. `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 de `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.

