Transformers documentation
SAM3 Tracker
Este modelo fue aportado a Hugging Face Transformers el 2025-11-19.
SAM3 Tracker
Resumen
SAM3 (Segment Anything Model 3) se presentó en SAM 3: Segment Anything with Concepts.
Sam3Tracker realiza Segmentación Visual con Prompts (PVS) en imágenes. PVS toma prompts visuales interactivos (puntos, cajas, máscaras) o entradas de texto para segmentar una instancia de objeto específica por prompt. Esta es la tarea en la que se centraron SAM 1 y SAM 2, y SAM 3 la mejora.
Sam3Tracker es una versión actualizada de SAM2 (Segment Anything Model 2) que mantiene la misma API mientras ofrece un rendimiento y capacidades mejorados.
El resumen del artículo es el siguiente:
Presentamos Segment Anything Model (SAM) 3, un modelo unificado que detecta, segmenta y realiza seguimiento de objetos en imágenes y videos basándose en prompts de concepto, que definimos como frases nominales cortas (p. ej., “yellow school bus”), ejemplos de imagen o una combinación de ambos. La Segmentación de Conceptos con Prompts (PCS) toma dichos prompts y devuelve máscaras de segmentación e identidades únicas para todas las instancias de objetos coincidentes. Para avanzar en PCS, construimos un motor de datos escalable que produce un conjunto de datos de alta calidad con 4M de etiquetas de concepto únicas, incluyendo negativos difíciles, en imágenes y videos. Nuestro modelo consiste en un detector a nivel de imagen y un rastreador de video basado en memoria que comparten un único backbone. El reconocimiento y la localización se desacoplan mediante una presencia head, lo que mejora la precisión de la detección. SAM 3 duplica la precisión de los sistemas existentes tanto en PCS de imágenes como de videos, y mejora las capacidades anteriores de SAM en tareas de segmentación visual. Publicamos SAM 3 en código abierto junto con nuestro nuevo benchmark Segment Anything with Concepts (SA-Co) para la segmentación de conceptos con prompts.
Este modelo fue aportado por yonigozlan y ronghanghu.
Ejemplo de uso
Generación automática de máscaras con Pipeline
Sam3Tracker se puede utilizar para la generación automática de máscaras y segmentar todos los objetos de una imagen mediante la 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
39Segmentación básica de imágenes
Clic en un solo punto
Puede segmentar objetos proporcionando un solo clic en el objeto que desea segmentar:
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])Varios puntos para la mejora
Puede proporcionar varios puntos para refinar la segmentación:
# 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]Entrada de caja delimitadora
Sam3Tracker también admite entradas de recuadro delimitador para segmentación:
# 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]Segmentación de múltiples objetos
Puede segmentar varios objetos simultáneamente:
# 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 objectsInferencia por lotes
Imágenes por lotes
Procesar varias imágenes simultáneamente para mejorar la eficiencia:
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 objectsObjetos por lote por imagen
Segmenta varios objetos en cada imagen mediante inferencia por lotes:
# 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"])Imágenes por lotes con objetos por lotes y múltiples puntos
Manejar escenarios de lotes complejos con múltiples puntos por objeto:
# 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"])Cajas delimitadoras por lotes
Procesar varias imágenes con entradas de recuadros delimitadores:
# 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 respectivelyUsar máscaras anteriores como entrada
Sam3Tracker puede usar máscaras de predicciones anteriores como entrada para refinar la segmentación:
# 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
clase transformers.Sam3TrackerConfig
< source >( 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 )
Parámetros
- vision_config (
Union[dict, ~configuration_utils.PreTrainedConfig], opcional) — El objeto de configuración o el diccionario del backbone de visión. - prompt_encoder_config (Union[
dict,Sam3TrackerPromptEncoderConfig], opcional) — Diccionario de opciones de configuración utilizado para inicializar Sam3TrackerPromptEncoderConfig. - mask_decoder_config (Union[
dict,Sam3TrackerMaskDecoderConfig], opcional) — Diccionario de opciones de configuración utilizado para inicializar Sam3TrackerMaskDecoderConfig. - initializer_range (
float, opcional, valor predeterminado0.02) — La desviación estándar del truncated_normal_initializer para inicializar todas las matrices de pesos.
Esta es la clase de configuración para almacenar la configuración de un Sam3TrackerModel. Se utiliza para instanciar un modelo Sam3 Tracker según los argumentos especificados, definiendo la arquitectura del modelo. Instanciar una configuración con los valores predeterminados producirá una configuración similar a la de facebook/sam3
Los objetos de configuración heredan de PreTrainedConfig y se pueden usar para controlar las salidas del modelo. Lea la documentación de PreTrainedConfig para obtener más información.
Ejemplo:
>>> 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
clase transformers.Sam3TrackerPromptEncoderConfig
< source >( 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 )
Parámetros
- hidden_size (
int, opcional, valor predeterminado256) — Dimensión de las representaciones ocultas. - image_size (
Union[int, list[int], tuple[int, int]], opcional, valor predeterminado1008) — El tamaño (resolución) de cada imagen. - patch_size (
Union[int, list[int], tuple[int, int]], opcional, valor predeterminado14) — El tamaño (resolución) de cada parche. - mask_input_channels (
int, opcional, valor predeterminado 16) — El número de canales que se enviarán al móduloMaskDecoder. - num_point_embeddings (
int, opcional, valor predeterminado 4) — El número de embeddings de puntos que se utilizarán. - hidden_act (
str, opcional, valor predeterminadogelu) — La función de activación no lineal (función o cadena) en el decodificador. Por ejemplo,"gelu","relu","silu", etc. - layer_norm_eps (
float, opcional, valor predeterminado1e-06) — La epsilon utilizada por las capas de normalización de capa. - scale (
float, opcional, valor predeterminado 1) — El factor de escala para el codificador de prompts.
Esta es la clase de configuración para almacenar la configuración de un Sam3TrackerModel. Se utiliza para instanciar un modelo Sam3 Tracker según los argumentos especificados, definiendo la arquitectura del modelo. Instanciar una configuración con los valores predeterminados producirá una configuración similar a la de facebook/sam3
Los objetos de configuración heredan de PreTrainedConfig y se pueden usar para controlar las salidas del modelo. Lea la documentación de PreTrainedConfig para obtener más información.
Sam3TrackerMaskDecoderConfig
clase transformers.Sam3TrackerMaskDecoderConfig
< source >( 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 )
Parámetros
- hidden_size (
int, opcional, valor predeterminado256) — Dimensión de las representaciones ocultas. - hidden_act (
str, opcional, valor predeterminadogelu) — La función de activación no lineal (función o cadena) en el decodificador. Por ejemplo,"gelu","relu","silu", etc. - mlp_dim (
int, opcional, valor predeterminado 2048) — La dimensión del MLP en el transformer de doble vía. - num_hidden_layers (
int, opcional, valor predeterminado2) — Número de capas ocultas en el decodificador del Transformer. - num_attention_heads (
int, opcional, valor predeterminado8) — Número de cabezas de atención para cada capa de atención en el decodificador Transformer. - attention_downsample_rate (
int, opcional, valor predeterminado 2) — La tasa de reducción de muestreo para las capas de atención. - num_multimask_outputs (
int, opcional, valor predeterminado 3) — El número de salidas multimask. - iou_head_depth (
int, opcional, valor predeterminado 3) — La profundidad de la cabeza de IoU. - iou_head_hidden_dim (
int, opcional, valor predeterminado 256) — La dimensión oculta de la cabeza de IoU. - dynamic_multimask_via_stability (
bool, opcional, valor predeterminadoTrue) — Si se debe usar la multimáscara dinámica a través de la estabilidad. - dynamic_multimask_stability_delta (
float, opcional, valor predeterminado 0.05) — El delta de estabilidad para la multimáscara dinámica. - dynamic_multimask_stability_thresh (
float, opcional, valor predeterminado 0.98) — Umbral de estabilidad para la multimáscara dinámica.
Esta es la clase de configuración para almacenar la configuración de un Sam3TrackerModel. Se utiliza para instanciar un modelo Sam3 Tracker según los argumentos especificados, definiendo la arquitectura del modelo. Instanciar una configuración con los valores predeterminados producirá una configuración similar a la de facebook/sam3
Los objetos de configuración heredan de PreTrainedConfig y se pueden usar para controlar las salidas del modelo. Lea la documentación de PreTrainedConfig para obtener más información.
Sam3TrackerProcessor
clase transformers.Sam3TrackerProcessor
< source >( image_processortarget_size: int | None = Nonepoint_pad_value: int = -10**kwargs )
Parámetros
- image_processor (
Sam3ImageProcessor) — El procesador de imágenes es una entrada obligatoria. - target_size (
int, opcional) — El tamaño objetivo (en píxeles) para normalizar los puntos de entrada y las cajas delimitadoras. Si no se proporciona, se usa el tamaño configurado en el procesador de imágenes por defecto. Todas las coordenadas de entrada (puntos y cajas) se normalizan a este tamaño antes de pasarse al modelo. Esto garantiza una representación de coordenadas coherente, independientemente de las dimensiones originales de la imagen. - point_pad_value (
int, opcional, valor predeterminado -10) — El valor utilizado para rellenar los puntos de entrada al agrupar secuencias de diferentes longitudes. Este valor se utiliza para marcar las posiciones rellenas y se conserva durante la normalización de coordenadas.
Construye un Sam3TrackerProcessor que envuelve un procesador de imágenes en un único procesador.
Sam3TrackerProcessor ofrece todas las funcionalidades de Sam3ImageProcessor. Consulte ~Sam3ImageProcessor para obtener más información.
__call__
< source >( 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
Parámetros
- images (
Union[PIL.Image.Image, numpy.ndarray, torch.Tensor, list[PIL.Image.Image], list[numpy.ndarray], list[torch.Tensor]], opcional) — Imagen a preprocesar. Espera una imagen única o un lote de imágenes con valores de píxeles que van de 0 a 255. Si se pasan imágenes con valores de píxeles entre 0 y 1, establezcado_rescale=False. - segmentation_maps (
ImageInput, opcional) — Los mapas de segmentación a procesar. - input_points (
list[list[list[list[float]]]],torch.Tensor, opcional) — Los puntos que se van a añadir al marco. - input_labels (
list[list[list[int]]],torch.Tensor, opcional) — Las etiquetas para los puntos. - input_boxes (
list[list[list[float]]],torch.Tensor, opcional) — Las cajas delimitadoras que se van a añadir al fotograma. - original_sizes (
list[list[float]],torch.Tensor, opcional) — Los tamaños originales de las imágenes. - return_tensors (
Union[str, ~utils.generic.TensorType], opcional) — Si se establece, devolverá tensores de un marco de trabajo específico. Los valores aceptables son:'pt': Devuelve objetostorch.Tensorde PyTorch.'np': Devuelve objetosnp.ndarrayde NumPy.
Devuelve
Un BatchEncoding con los siguientes campos
pixel_values(torch.Tensor): La(s) imagen(es) procesada(s).original_sizes(list[list[float]]): Los tamaños originales de las imágenes.labels(torch.Tensor): Los mapas de segmentación procesados (si se proporcionan).input_points(torch.Tensor): Los puntos procesados.input_labels(torch.Tensor): Las etiquetas procesadas.input_boxes(torch.Tensor): Las cajas delimitadoras procesadas.
post_process_masks
< source >( masksoriginal_sizesmask_threshold = 0.0binarize = Truemax_hole_area = 0.0max_sprinkle_area = 0.0apply_non_overlapping_constraints = False**kwargs ) → (torch.Tensor)
Parámetros
- masks (
Union[List[torch.Tensor], List[np.ndarray]]) — Máscaras por lotes del mask_decoder en formato (batch_size, num_channels, height, width). - original_sizes (
Union[torch.Tensor, List[Tuple[int,int]]]) — Los tamaños originales de cada imagen antes de que se redimensionara a la forma de entrada esperada por el modelo, en formato (altura, ancho). - mask_threshold (
float, opcional, valor predeterminado 0.0) — Umbral para las operaciones de binarización y posprocesamiento. - binarize (
bool, opcional, valor predeterminadoTrue) — Si se deben binarizar las máscaras. - max_hole_area (
float, opcional, valor predeterminado 0.0) — El área máxima de un agujero que se rellenará. - max_sprinkle_area (
float, opcional, valor predeterminado 0.0) — El área máxima de un sprinkle para rellenar. - apply_non_overlapping_constraints (
bool, opcional, valor predeterminadoFalse) — Si se aplican restricciones de no superposición a las máscaras.
Devuelve
(torch.Tensor)
Máscaras por lotes en el formato batch_size, num_channels, height, width, donde (height, width) está dado por original_size.
Eliminar el relleno y ampliar las máscaras al tamaño original de la imagen.
Sam3TrackerModel
clase transformers.Sam3TrackerModel
< source >( config: Sam3TrackerConfig )
Parámetros
- config (Sam3TrackerConfig) — Clase de configuración del modelo con todos los parámetros del modelo. Inicializar con un archivo de configuración no carga los pesos asociados con el modelo, solo la configuración. Consulte el método from_pretrained() para cargar los pesos del modelo.
Segment Anything Model 2 (SAM 2) para generar máscaras de segmentación, a partir de una imagen de entrada y puntos y etiquetas, cajas o máscaras de entrada.
Este modelo hereda de PreTrainedModel. Consulta la documentación de la clase superior para los métodos genéricos que la biblioteca implementa para todos sus modelos (como la descarga o el guardado, el redimensionamiento de las incrustaciones de entrada, la poda de cabezas, etc.).
Este modelo también es una subclase de torch.nn.Module de PyTorch. Úsalo como un módulo de PyTorch regular y consulta la documentación de PyTorch para todo lo relacionado con el uso y el comportamiento generales.
forward
< source >( 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)
Parámetros
- pixel_values (
torch.Tensorde forma(batch_size, num_channels, image_size, image_size), opcional) — Los tensores correspondientes a las imágenes de entrada. Los valores de píxeles se pueden obtener utilizando Sam3ImageProcessor. Consulte Sam3ImageProcessor.call() para más detalles (Sam3TrackerProcessor utiliza Sam3ImageProcessor para procesar las imágenes). - input_points (
torch.Tensorde forma(batch_size, num_points, 2)) — Puntos espaciales 2D de entrada, que se utilizan en el codificador de prompts para codificar el prompt. Generalmente produce resultados mucho mejores. Los puntos se pueden obtener pasando una lista de listas de listas al procesador, que creará los correspondientes tensorestorchde dimensión 4. La primera dimensión es el tamaño del lote de imágenes, la segunda dimensión es el tamaño del lote de puntos (es decir, cuántas máscaras de segmentación queremos que el modelo prediga por punto de entrada), la tercera dimensión es el número de puntos por máscara de segmentación (es posible pasar varios puntos para una sola máscara) y la última dimensión son las coordenadas x (vertical) y y (horizontal) del punto. Si se pasa un número diferente de puntos para cada imagen o para cada máscara, el procesador creará puntos “PAD” que corresponderán a la coordenada (0, 0) y el cálculo del embedding se omitirá para estos puntos usando las etiquetas. - input_labels (
torch.LongTensorde forma(batch_size, point_batch_size, num_points)) — Etiquetas de entrada para los puntos, que se utilizan en el codificador de prompts para codificar el prompt. Según la implementación oficial, hay 3 tipos de etiquetas1: el punto es un punto que contiene el objeto de interés0: el punto es un punto que no contiene el objeto de interés-1: el punto corresponde al fondo
Añadimos la etiqueta:
-10: el punto es un punto de relleno, por lo que debe ser ignorado por el codificador de prompts
Las etiquetas de relleno deberían ser asignadas automáticamente por el procesador.
- input_boxes (
torch.Tensorde forma(batch_size, num_boxes, 4)) — Cajas de entrada para los puntos, se utiliza en el codificador de prompts para codificar el prompt. Generalmente produce máscaras generadas mucho mejores. Las cajas se pueden obtener pasando una lista de listas de listas al procesador, que generará untorchtensor, donde cada dimensión corresponde respectivamente al tamaño del lote de imágenes, al número de cajas por imagen y a las coordenadas del punto superior izquierdo y del punto inferior derecho de la caja. En el orden (x1,y1,x2,y2):x1: la coordenada x del punto superior izquierdo del cuadro de entraday1: la coordenada y del punto superior izquierdo del cuadro de entradax2: la coordenada x del punto inferior derecho del cuadro de entraday2: la coordenada y del punto inferior derecho del cuadro de entrada
- input_masks (
torch.Tensorde forma(batch_size, image_size, image_size)) — El modelo SAM también acepta máscaras de segmentación como entrada. La máscara se incrustará mediante el codificador de prompts para generar una incrustación correspondiente, que se enviará posteriormente al decodificador de máscaras. Estas máscaras deben ser proporcionadas manualmente por el usuario y deben tener la forma (batch_size,image_size,image_size). - image_embeddings (
torch.Tensorde forma(batch_size, output_channels, window_size, window_size)) — Incrustaciones de imagen, se utilizan en el decodificador de máscaras para generar máscaras y puntuaciones iou. Para un cálculo más eficiente en memoria, los usuarios pueden obtener primero las incrustaciones de imagen mediante el métodoget_image_embeddingsy luego pasarlas al métodoforwarden lugar de pasarpixel_values. - multimask_output (
bool, opcional) — En la implementación y el artículo originales, el modelo siempre genera 3 máscaras por imagen (o por punto / por bounding box, si corresponde). Sin embargo, es posible generar una sola máscara, que corresponde a la máscara “mejor”, especificandomultimask_output=False. - attention_similarity (
torch.Tensor, opcional) — Tensor de similitud de atención, que debe proporcionarse al decodificador de máscaras para la atención guiada por objetivos en caso de que el modelo se utilice para personalización, tal como se introduce en PerSAM. - target_embedding (
torch.Tensor, opcional) — Incrustación del concepto objetivo, que debe proporcionarse al decodificador de máscaras para el prompting semántico del objetivo en caso de que el modelo se utilice para personalización, tal como se introduce en PerSAM.
Devuelve
Sam3TrackerImageSegmentationOutput o tuple(torch.Tensor)
Un Sam3TrackerImageSegmentationOutput o una tupla de
torch.Tensor (si se pasa return_dict=False o cuando config.return_dict=False) que comprende varios
elementos según la configuración (Sam3TrackerConfig) y las entradas.
El método forward de Sam3TrackerModel reemplaza el método especial __call__.
Aunque la receta para la pasada hacia adelante debe definirse dentro de esta función, se debe llamar a la instancia de
Moduledespués en lugar de a esta, ya que la primera se encarga de ejecutar los pasos de pre y postprocesamiento, mientras que la segunda los ignora silenciosamente.
- iou_scores (
torch.Tensorde forma(batch_size, point_batch_size, num_masks)) — Las puntuaciones de Intersección sobre Unión (IoU) de las máscaras predichas. - pred_masks (
torch.Tensorde forma(batch_size, point_batch_size, num_masks, height, width)) — Las máscaras de baja resolución predichas. Esto es un alias delow_res_masks. Estas máscaras deben ser procesadas posteriormente por el procesador para llevarlas al tamaño original de la imagen. - object_score_logits (
torch.Tensorde forma(batch_size, point_batch_size, 1)) — Logits para la puntuación del objeto, que indican si está presente un objeto. - image_embeddings (
tuple(torch.Tensor)) — Las características del FPN, que utiliza el decodificador de máscaras. Es una tupla detorch.Tensordonde cada tensor tiene forma(batch_size, channels, height, width). - vision_hidden_states (
tuple(torch.Tensor), opcional, se devuelve cuandooutput_hidden_states=True) — Tupla detorch.Tensor(uno para la salida de cada etapa) de forma(batch_size, height, width, hidden_size). Estados ocultos del modelo de visión en la salida de cada etapa. - vision_attentions (
tuple(torch.Tensor), opcional, se devuelve cuandooutput_attentions=True) — Tupla detorch.Tensor(una por cada capa) de forma(batch_size, num_heads, sequence_length, sequence_length). Pesos de atención del modelo de visión. - mask_decoder_attentions (
tuple(torch.Tensor), opcional, devuelto cuandooutput_attentions=True) — Tupla detorch.Tensor(uno por cada capa) de forma(batch_size, num_heads, sequence_length, sequence_length). Pesos de atención del decodificador de máscaras.
Ejemplo:
>>> 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
< source >( pixel_values: Tensor**kwargs: *<class 'transformers.utils.generic.TransformersKwargs'> ) → Sam3TrackerVisionEncoderOutput or tuple(torch.Tensor)
Parámetros
- pixel_values (
torch.Tensor) — Valores de píxeles de entrada con forma(batch_size, num_channels, height, width).
Devuelve
Sam3TrackerVisionEncoderOutput o tuple(torch.Tensor)
Un Sam3TrackerVisionEncoderOutput o una tupla de
torch.Tensor (si se pasa return_dict=False o cuando config.return_dict=False) que comprende varios
elementos según la configuración (Sam3TrackerConfig) y las entradas.
last_hidden_state (
torch.Tensorde forma(batch_size, height, width, hidden_size)) — Secuencia de estados ocultos en la salida de la última capa del modelo.pooler_output (
torch.Tensorde forma(batch_size, hidden_size)) — Estado oculto de la última capa del primer token de la secuencia (token de clasificación) después de un procesamiento adicional a través de las capas utilizadas para la tarea de preentrenamiento auxiliar. Por ejemplo, para la familia de modelos BERT, esto devuelve el token de clasificación después de procesarlo a través de una capa lineal y una función de activación tanh. Los pesos de la capa lineal se entrenan a partir del objetivo de predicción de la siguiente oración (clasificación) durante el preentrenamiento.hidden_states (
tuple(torch.Tensor), opcional, devuelto cuando se pasaoutput_hidden_states=Trueo cuandoconfig.output_hidden_states=True) — Tupla detorch.Tensor(una para la salida de las incrustaciones, si el modelo tiene una capa de incrustaciones, + una para la salida de cada capa) de forma(batch_size, sequence_length, hidden_size).Estados ocultos del modelo en la salida de cada capa más las salidas opcionales de la incrustación inicial.
attentions (
tuple(torch.Tensor), opcional, se devuelve cuando se pasaoutput_attentions=Trueo cuandoconfig.output_attentions=True) — Tupla detorch.Tensor(una por cada capa) de forma(batch_size, num_heads, sequence_length, sequence_length).Pesos de atención tras el softmax de atención, utilizados para calcular la media ponderada en las cabezas de autoatención.
fpn_hidden_states (
tuple(torch.Tensor)) — Tupla detorch.Tensor(uno para cada nivel de características, de alta a baja resolución) de forma(batch_size, hidden_size, height, width). Mapas de características del cuello de la Feature Pyramid Network.fpn_position_encoding (
tuple(torch.Tensor)) — Tupla detorch.Tensor(una para cada nivel de características, de alta a baja resolución) de forma(batch_size, hidden_size, height, width). Codificaciones posicionales correspondientes afpn_hidden_states.
Sam3TrackerPreTrainedModel
clase transformers.Sam3TrackerPreTrainedModel
< source >( config: PreTrainedConfig*inputs**kwargs )
Parámetros
- config (PreTrainedConfig) — Clase de configuración del modelo con todos los parámetros del modelo. Inicializar con un archivo de configuración no carga los pesos asociados con el modelo, solo la configuración. Consulte el método from_pretrained() para cargar los pesos del modelo.
Segment Anything Model 3 (SAM 3) para generar máscaras de segmentación, a partir de una imagen de entrada y puntos y etiquetas, cajas o máscaras de entrada.
Un valor simulado para una ruta con puntos (p. ej. torch.float32): las cadenas de acceso a atributos y las llamadas se comportan como decoradores de paso, repr es la ruta con puntos, y su uso como clase base sustituye una base de type simple (PEP 560 __mro_entries__), de modo que las subclases reales conservan un metaclass normal y inspect.signature lee su __init__ real en lugar del de un simulado.