Hugging Face's logo

Transformers documentation

Трекер SAM3

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

Эта модель была добавлена в Hugging Face Transformers 19.11.2025.

Трекер SAM3

SDPA FlashAttention

Обзор

SAM3 (Segment Anything Model 3) был представлен в статье SAM 3: Segment Anything with Concepts.

Sam3Tracker выполняет Promptable Visual Segmentation (PVS) на изображениях. PVS использует интерактивные визуальные подсказки (точки, рамки, маски) или текстовые входные данные для сегментации конкретного экземпляра объекта по каждой подсказке. Именно на этой задаче фокусировались SAM 1 и SAM 2, а SAM 3 улучшает её.

Sam3Tracker — это обновленная версия SAM2 (Segment Anything Model 2), которая сохраняет тот же API, но обеспечивает улучшенную производительность и расширенные возможности.

Аннотация из статьи следующая:

Мы представляем Segment Anything Model (SAM) 3 — унифицированную модель, которая обнаруживает, сегментирует и отслеживает объекты на изображениях и в видео на основе концептуальных промптов, которые мы определяем как короткие существительные (например, «жёлтый школьный автобус»), образцы изображений или комбинацию обоих. Promptable Concept Segmentation (PCS) принимает такие промпты и возвращает маски сегментации и уникальные идентификаторы для всех соответствующих экземпляров объектов. Для развития PCS мы создали масштабируемый движок данных, который формирует высококачественный датасет с 4 млн уникальных концептуальных меток, включая сложные негативные примеры, для изображений и видео. Наша модель состоит из детектора на уровне изображения и видео-трекера на основе памяти, которые используют общий бэкбон. Распознавание и локализация разделены с помощью presence head, что повышает точность обнаружения. SAM 3 удваивает точность существующих систем как в PCS для изображений, так и для видео, а также улучшает возможности предыдущих версий SAM в задачах визуальной сегментации. Мы открыли исходный код SAM 3 вместе с нашим новым бенчмарком Segment Anything with Concepts (SA-Co) для promptable concept segmentation.

Эта модель была предоставлена yonigozlan и ronghanghu.

Пример использования

Автоматическая генерация масок с помощью Pipeline

Sam3Tracker можно использовать для автоматической генерации масок, чтобы сегментировать все объекты на изображении с помощью конвейера 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

Базовая сегментация изображений

Одиночный щелчок

Вы можете сегментировать объекты, выполнив один клик по объекту, который нужно сегментировать:

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

Несколько точек для уточнения

Вы можете указать несколько точек для уточнения сегментации:

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

Входные данные ограничивающего прямоугольника

Sam3Tracker также поддерживает входные данные в виде ограничивающих прямоугольников для сегментации:

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

Сегментация нескольких объектов

Вы можете сегментировать несколько объектов одновременно:

# 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

Пакетный вывод

Пакетные изображения

Обрабатывайте несколько изображений одновременно для повышения эффективности:

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

Пакетные объекты на изображение

Сегментируйте несколько объектов на каждом изображении с помощью пакетного вывода:

# 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"])

Пакетные изображения с пакетными объектами и несколькими точками

Обработка сложных сценариев батчей с несколькими точками на объект:

# 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"])

Пакетные ограничивающие рамки

Обработка нескольких изображений с входными данными в виде ограничивающих прямоугольников:

# 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

Использование предыдущих масок в качестве входных данных

Sam3Tracker может использовать маски из предыдущих предсказаний в качестве входных данных для уточнения сегментации:

# 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_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 )

Параметры

  • vision_config (Union[dict, ~configuration_utils.PreTrainedConfig], необязательный) — Объект конфигурации или словарь конфигурации визуального бэкбона.
  • prompt_encoder_config (Union[dict, Sam3TrackerPromptEncoderConfig], необязательный) — Словарь с параметрами конфигурации, используемыми для инициализации Sam3TrackerPromptEncoderConfig.
  • mask_decoder_config (Union[dict, Sam3TrackerMaskDecoderConfig], необязательный) — Словарь с параметрами конфигурации, используемыми для инициализации Sam3TrackerMaskDecoderConfig.
  • initializer_range (float, необязательный, по умолчанию 0.02) — Стандартное отклонение truncated_normal_initializer, используемое для инициализации всех матриц весов.

Это класс конфигурации для хранения настроек модели Sam3TrackerModel. Он используется для создания модели Sam3 Tracker в соответствии с указанными аргументами, определяя архитектуру модели. Создание конфигурации с параметрами по умолчанию даст конфигурацию, аналогичную конфигурации facebook/sam3

Объекты конфигурации наследуются от PreTrainedConfig и могут использоваться для управления выводами модели. Подробнее читайте в документации PreTrainedConfig.

Пример:

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

Параметры

  • hidden_size (int, необязательный, по умолчанию 256) — Размерность скрытых представлений.
  • image_size (Union[int, list[int], tuple[int, int]], необязательный, по умолчанию 1008) — Размер (разрешение) каждого изображения.
  • patch_size (Union[int, list[int], tuple[int, int]], необязательный, по умолчанию 14) — Размер (разрешение) каждого патча.
  • mask_input_channels (int, необязательный, по умолчанию 16) — Количество каналов, передаваемых в модуль MaskDecoder.
  • num_point_embeddings (int, необязательный, по умолчанию 4) — Количество используемых точечных эмбеддингов.
  • hidden_act (str, необязательный, по умолчанию gelu) — Нелинейная функция активации (функция или строка) в декодере. Например, "gelu", "relu", "silu" и т. д.
  • layer_norm_eps (float, необязательный, по умолчанию 1e-06) — Значение epsilon, используемое слоями нормализации.
  • scale (float, необязательный, по умолчанию 1) — Коэффициент масштабирования для кодировщика промпта.

Это класс конфигурации для хранения настроек модели Sam3TrackerModel. Он используется для создания модели Sam3 Tracker в соответствии с указанными аргументами, определяя архитектуру модели. Создание конфигурации с параметрами по умолчанию даст конфигурацию, аналогичную конфигурации facebook/sam3

Объекты конфигурации наследуются от PreTrainedConfig и могут использоваться для управления выводами модели. Подробнее читайте в документации PreTrainedConfig.

Sam3TrackerMaskDecoderConfig

класс 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 )

Параметры

  • hidden_size (int, необязательный, по умолчанию 256) — Размерность скрытых представлений.
  • hidden_act (str, необязательный, по умолчанию gelu) — Нелинейная функция активации (функция или строка) в декодере. Например, "gelu", "relu", "silu" и т. д.
  • mlp_dim (int, необязательный, по умолчанию 2048) — Размерность MLP в двухстороннем трансформере.
  • num_hidden_layers (int, необязательный, по умолчанию 2) — Количество скрытых слоев в декодере Transformer.
  • num_attention_heads (int, необязательный, по умолчанию 8) — Количество головок внимания в каждом слое внимания декодера Transformer.
  • attention_downsample_rate (int, необязательный, по умолчанию 2) — Коэффициент понижающей дискретизации для слоев внимания.
  • num_multimask_outputs (int, необязательный, по умолчанию 3) — Количество выходов multimask.
  • iou_head_depth (int, необязательный, по умолчанию 3) — Глубина IoU-головы.
  • iou_head_hidden_dim (int, необязательный, по умолчанию 256) — Скрытое измерение IoU-головы.
  • dynamic_multimask_via_stability (bool, необязательный, по умолчанию True) — Использовать ли динамическую мультимаску через стабильность.
  • dynamic_multimask_stability_delta (float, необязательный, по умолчанию 0.05) — Дельта стабильности для динамической мультимаски.
  • dynamic_multimask_stability_thresh (float, необязательный, по умолчанию 0.98) — Порог стабильности для динамической мультимаски.

Это класс конфигурации для хранения настроек модели Sam3TrackerModel. Он используется для создания модели Sam3 Tracker в соответствии с указанными аргументами, определяя архитектуру модели. Создание конфигурации с параметрами по умолчанию даст конфигурацию, аналогичную конфигурации facebook/sam3

Объекты конфигурации наследуются от PreTrainedConfig и могут использоваться для управления выводами модели. Подробнее читайте в документации PreTrainedConfig.

Sam3TrackerProcessor

класс transformers.Sam3TrackerProcessor

< >

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

Параметры

  • image_processor (Sam3ImageProcessor) — Обработчик изображений является обязательным входным параметром.
  • target_size (int, необязательный) — Целевой размер (в пикселях) для нормализации входных точек и ограничивающих прямоугольников. Если не указан, по умолчанию используется конфигурация размера процессора изображений. Все входные координаты (точки и прямоугольники) нормализуются до этого размера перед передачей в модель. Это обеспечивает единообразное представление координат независимо от исходных размеров изображения.
  • point_pad_value (int, необязательный, по умолчанию -10) — Значение, используемое для дополнения входных точек при пакетной обработке последовательностей разной длины. Это значение используется для пометки дополненных позиций и сохраняется при нормализации координат.

Создаёт Sam3TrackerProcessor, который объединяет процессор изображений в единый процессор.

Sam3TrackerProcessor предоставляет все возможности Sam3ImageProcessor. Подробнее см. в ~Sam3ImageProcessor.

__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

Параметры

  • images (Union[PIL.Image.Image, numpy.ndarray, torch.Tensor, list[PIL.Image.Image], list[numpy.ndarray], list[torch.Tensor]], необязательный) — Изображение для предобработки. Ожидается одно изображение или батч изображений со значениями пикселей в диапазоне от 0 до 255. Если передаются изображения со значениями пикселей в диапазоне от 0 до 1, установите do_rescale=False.
  • segmentation_maps (ImageInput, необязательный) — Сегментационные карты для обработки.
  • input_points (list[list[list[list[float]]]], torch.Tensor, необязательный) — Точки, которые нужно добавить в кадр.
  • input_labels (list[list[list[int]]], torch.Tensor, необязательный) — Метки для точек.
  • input_boxes (list[list[list[float]]], torch.Tensor, необязательный) — Ограничивающие рамки, которые нужно добавить к кадру.
  • original_sizes (list[list[float]], torch.Tensor, необязательный) — Исходные размеры изображений.
  • return_tensors (Union[str, ~utils.generic.TensorType], необязательный) — Если задано, возвращает тензоры конкретного фреймворка. Допустимые значения:
    • 'pt': возвращает объекты torch.Tensor PyTorch.
    • 'np': возвращает объекты NumPy np.ndarray.

Возвращает

BatchEncoding со следующими полями

  • pixel_values (torch.Tensor): Обработанное изображение или изображения.
  • original_sizes (list[list[float]]): исходные размеры изображений.
  • labels (torch.Tensor): Обработанные карты сегментации (если предоставлены).
  • input_points (torch.Tensor): Обработанные точки.
  • input_labels (torch.Tensor): Обработанные метки.
  • input_boxes (torch.Tensor): Обработанные ограничивающие рамки.

post_process_masks

< >

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

Параметры

  • masks (Union[List[torch.Tensor], List[np.ndarray]]) — Пакетные маски из mask_decoder в формате (batch_size, num_channels, height, width).
  • original_sizes (Union[torch.Tensor, List[Tuple[int,int]]]) — Исходные размеры каждого изображения до его масштабирования до ожидаемой входной формы модели, в формате (высота, ширина).
  • mask_threshold (float, необязательный, по умолчанию 0.0) — Порог для бинаризации и операций постобработки.
  • binarize (bool, необязательный, по умолчанию True) — Указывает, следует ли бинаризировать маски.
  • max_hole_area (float, необязательный, по умолчанию 0.0) — Максимальная площадь отверстия, подлежащего заполнению.
  • max_sprinkle_area (float, необязательный, по умолчанию 0.0) — Максимальная площадь sprinkle, подлежащая заполнению.
  • apply_non_overlapping_constraints (bool, необязательный, по умолчанию False) — Указывает, следует ли применять ограничения на отсутствие перекрытий к маскам.

Возвращает

(torch.Tensor)

Маски в формате batch_size, num_channels, height, width, где (height, width) определяется параметром original_size.

Удалите заполнение (padding) и масштабируйте маски до исходного размера изображения.

Sam3TrackerModel

класс transformers.Sam3TrackerModel

< >

( config: Sam3TrackerConfig )

Параметры

  • config (Sam3TrackerConfig) — Класс конфигурации модели, содержащий все параметры модели. Инициализация с помощью файла конфигурации не загружает веса, связанные с моделью, а только конфигурацию. Используйте метод from_pretrained() для загрузки весов модели.

Segment Anything Model 2 (SAM 2) для генерации сегментационных масок по входному изображению и входным точкам и меткам, рамкам или маскам.

Эта модель наследуется от PreTrainedModel. См. документацию родительского класса для общих методов, которые библиотека реализует для всех своих моделей (например, загрузка или сохранение, изменение размера входных эмбеддингов, обрезка голов и т. д.)

Эта модель также является подклассом torch.nn.Module в PyTorch. Используйте её как обычный модуль PyTorch и обращайтесь к документации PyTorch по всем вопросам, связанным с общим использованием и поведением.

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)

Параметры

  • pixel_values (torch.Tensor формы (batch_size, num_channels, image_size, image_size), необязательный) — Тензоры, соответствующие входным изображениям. Значения пикселей можно получить с помощью Sam3ImageProcessor. Подробности см. в Sam3ImageProcessor.call() (Sam3TrackerProcessor использует Sam3ImageProcessor для обработки изображений).
  • input_points (torch.Tensor формы (batch_size, num_points, 2)) — Входные 2D пространственные точки, которые используются кодировщиком промпта для кодирования промпта. Как правило, это дает значительно лучшие результаты. Точки можно получить, передав процессору список списков списков, который создаст соответствующие тензоры torch размерности 4. Первая размерность — размер батча изображений, вторая — размер батча точек (то есть сколько сегментационных масок модель должна предсказать на каждую входную точку), третья — количество точек на сегментационную маску (можно передать несколько точек для одной маски), а последняя — координаты x (вертикальная) и y (горизонтальная) точки. Если для каждого изображения или для каждой маски передано разное количество точек, процессор создаст точки «PAD», соответствующие координате (0, 0), и вычисление эмбеддинга для этих точек будет пропущено с использованием меток.
  • input_labels (torch.LongTensor формы (batch_size, point_batch_size, num_points)) — Входные метки для точек. Используются prompt encoder для кодирования промпта. Согласно официальному реализованию, существует 3 типа меток
    • 1: точка, содержащая объект интереса
    • 0: точка, не содержащая объекта интереса
    • -1: точка соответствует фону

    Мы добавили метку:

    • -10: точка является заполнителем, поэтому должна игнорироваться prompt encoder

    Метки для отступов должны добавляться автоматически процессором.

  • input_boxes (torch.Tensor формы (batch_size, num_boxes, 4)) — Входные рамки для точек. Используются prompt encoder для кодирования промпта. Как правило, это приводит к значительно более качественным сгенерированным маскам. Рамки можно получить, передав в processor список списков списков, который сгенерирует torch тензор, где каждое измерение соответствует размеру батча изображений, количеству рамок на изображение и координатам верхней левой и нижней правой точек рамки. В порядке (x1, y1, x2, y2):
    • x1: координата x верхней левой точки входного прямоугольника
    • y1: координата y верхней левой точки входного прямоугольника
    • x2: координата x правого нижнего угла входного прямоугольника
    • y2: координата y нижней правой точки входного прямоугольника
  • input_masks (torch.Tensor формы (batch_size, image_size, image_size)) — Модель SAM также принимает в качестве входных данных маски сегментации. Маска будет закодирована prompt encoder для генерации соответствующего эмбеддинга, который затем будет передан в mask decoder. Эти маски необходимо вручную передавать пользователем, и они должны иметь форму (batch_size, image_size, image_size).
  • image_embeddings (torch.Tensor формы (batch_size, output_channels, window_size, window_size)) — Векторные представления изображений, которые используются декодером масок для генерации масок и оценок iou. Для более эффективного использования памяти пользователи могут сначала получить векторные представления изображений с помощью метода get_image_embeddings, а затем передать их в метод forward вместо передачи pixel_values.
  • multimask_output (bool, необязательный) — В исходной реализации и статье модель всегда выводит 3 маски на изображение (или на точку / на ограничивающий прямоугольник, если это применимо). Однако можно вывести только одну маску, соответствующую «лучшей» маске, указав multimask_output=False.
  • attention_similarity (torch.Tensor, необязательный) — Тензор сходства внимания, который передается декодеру маски для целевого управления вниманием, если модель используется для персонализации, как описано в PerSAM.
  • target_embedding (torch.Tensor, необязательный) — Векторное представление целевого концепта, которое передается декодеру маски для семантического промптинга по целевому объекту, если модель используется для персонализации, как описано в PerSAM.

Возвращает

Sam3TrackerImageSegmentationOutput или tuple(torch.Tensor)

Sam3TrackerImageSegmentationOutput или кортеж из torch.Tensor (если передано return_dict=False или если config.return_dict=False), содержащий различные элементы в зависимости от конфигурации (Sam3TrackerConfig) и входных данных.

Метод forward модели Sam3TrackerModel переопределяет специальный метод __call__.

Хотя рецепт для прямого прохода должен быть определён внутри этой функции, после этого следует вызывать экземпляр Module, а не эту функцию, поскольку первый вариант обеспечивает выполнение шагов предварительной и последующей обработки, тогда как второй молча их игнорирует.

  • iou_scores (torch.Tensor формы (batch_size, point_batch_size, num_masks)) — Оценки пересечения по объединению (IoU) для предсказанных масок.
  • pred_masks (torch.Tensor формы (batch_size, point_batch_size, num_masks, height, width)) — Предсказанные маски низкого разрешения. Это псевдоним для low_res_masks. Эти маски необходимо постобработать с помощью процессора, чтобы привести их к размеру исходного изображения.
  • object_score_logits (torch.Tensor формы (batch_size, point_batch_size, 1)) — Логиты оценки объекта, указывающие на наличие объекта.
  • image_embeddings (tuple(torch.Tensor)) — признаки из FPN, используемые декодером масок. Это кортеж torch.Tensor, где каждый тензор имеет форму (batch_size, channels, height, width).
  • vision_hidden_states (tuple(torch.Tensor), необязательный, возвращается при output_hidden_states=True) — Кортеж torch.Tensor (по одному на выход каждого этапа) формы (batch_size, height, width, hidden_size). Скрытые состояния модели зрения на выходе каждого этапа.
  • vision_attentions (tuple(torch.Tensor), необязательный, возвращается при output_attentions=True) — Кортеж torch.Tensor (по одному на каждый слой) формы (batch_size, num_heads, sequence_length, sequence_length). Веса внимания визуальной модели.
  • mask_decoder_attentions (tuple(torch.Tensor), optional, возвращается при output_attentions=True) — Кортеж torch.Tensor (по одному на каждый слой) формы (batch_size, num_heads, sequence_length, sequence_length). Веса внимания mask decoder.

Пример:

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

Параметры

  • pixel_values (torch.Tensor) — Входные значения пикселей формы (batch_size, num_channels, height, width).

Возвращает

Sam3TrackerVisionEncoderOutput или tuple(torch.Tensor)

Sam3TrackerVisionEncoderOutput или кортеж из torch.Tensor (если передано return_dict=False или если config.return_dict=False), содержащий различные элементы в зависимости от конфигурации (Sam3TrackerConfig) и входных данных.

  • last_hidden_state (torch.Tensor формы (batch_size, height, width, hidden_size)) — Последовательность скрытых состояний на выходе последнего слоя модели.

  • pooler_output (torch.Tensor формы (batch_size, hidden_size)) — Скрытое состояние последнего слоя для первого токена последовательности (токен классификации) после дополнительной обработки слоями, используемыми для вспомогательной задачи предварительного обучения. Например, для моделей семейства BERT это возвращает токен классификации после обработки линейным слоем и функцией активации tanh. Веса линейного слоя обучаются по задаче предсказания следующего предложения (классификации) во время предварительного обучения.

  • hidden_states (tuple(torch.Tensor), optional, возвращается, если передано output_hidden_states=True или если config.output_hidden_states=True) — кортеж из torch.Tensor (один для вывода слоя встраиваний, если модель имеет слой встраиваний, + один для вывода каждого слоя) формы (batch_size, sequence_length, hidden_size).

    Скрытые состояния модели на выходе каждого слоя, а также необязательные выходные значения начального слоя встраивания.

  • attentions (tuple(torch.Tensor), необязательный, возвращается при передаче output_attentions=True или при config.output_attentions=True) — Кортеж torch.Tensor (по одному на каждый слой) формы (batch_size, num_heads, sequence_length, sequence_length).

    Веса внимания после softmax в механизме внимания, используемые для вычисления взвешенного среднего в головах само-внимания.

  • fpn_hidden_states (tuple(torch.Tensor)) — Кортеж torch.Tensor (по одному для каждого уровня признаков, от высокого разрешения к низкому) формы (batch_size, hidden_size, height, width). Карты признаков из шейки Feature Pyramid Network.

  • fpn_position_encoding (tuple(torch.Tensor)) — Кортеж torch.Tensor (по одному для каждого уровня признаков, от высокого разрешения к низкому) с формой (batch_size, hidden_size, height, width). Позиционные кодировки, соответствующие fpn_hidden_states.

Пример:

Sam3TrackerPreTrainedModel

класс transformers.Sam3TrackerPreTrainedModel

< >

( config: PreTrainedConfig*inputs**kwargs )

Параметры

  • config (PreTrainedConfig) — Класс конфигурации модели, содержащий все параметры модели. Инициализация с помощью файла конфигурации не загружает веса, связанные с моделью, а только конфигурацию. Чтобы загрузить веса модели, используйте метод from_pretrained().

Segment Anything Model 3 (SAM 3) для генерации сегментационных масок по входному изображению и входным точкам с метками, рамкам или маскам.

forward

( *args**kwargs )

Мок-значение для пути с точками (например, torch.float32): цепочки доступа к атрибутам и вызовы работают как пропускные декораторы, repr возвращает путь с точками, а использование в качестве базового класса подставляет обычный базовый класс type (PEP 560 __mro_entries__), благодаря чему реальные дочерние классы сохраняют обычный метакласс, а inspect.signature читает их реальный __init__, а не мок-объект.

Update on GitHub

←SAM2 Sapiens2→