Transformers documentation

SAM3 Tracker

Transformers

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

Join the Hugging Face community

and get access to the augmented documentation experience

Collaborate on models, datasets and Spaces

Faster examples with accelerated inference

Switch between documentation themes

to get started

Model ini disumbangkan ke Hugging Face Transformers pada 2025-11-19.

SAM3 Tracker

Ikhtisar

SAM3 (Segment Anything Model 3) diperkenalkan dalam SAM 3: Segment Anything with Concepts.

Sam3Tracker melakukan Promptable Visual Segmentation (PVS) pada gambar. PVS menerima prompt visual interaktif (titik, kotak, mask) atau input teks untuk memsegmentasi instans objek tertentu per prompt. Ini adalah tugas yang menjadi fokus SAM 1 dan SAM 2, dan SAM 3 memperbaikinya.

Sam3Tracker adalah versi pembaruan dari SAM2 (Segment Anything Model 2) yang mempertahankan API yang sama sambil menyediakan kinerja dan kemampuan yang lebih baik.

Abstrak dari makalah tersebut adalah sebagai berikut:

Kami memperkenalkan Segment Anything Model (SAM) 3, sebuah model terpadu yang mendeteksi, memsegmentasi, dan melacak objek dalam gambar dan video berdasarkan prompt konsep, yang kami definisikan sebagai frasa nomina pendek (misalnya, “yellow school bus”), contoh gambar, atau kombinasi keduanya. Promptable Concept Segmentation (PCS) menerima prompt semacam itu dan mengembalikan mask segmentasi serta identitas unik untuk semua instans objek yang cocok. Untuk memajukan PCS, kami membangun mesin data yang dapat diskalakan yang menghasilkan dataset berkualitas tinggi dengan 4 juta label konsep unik, termasuk negatif yang sulit, di seluruh gambar dan video. Model kami terdiri dari detektor tingkat gambar dan pelacak video berbasis memori yang berbagi satu backbone tunggal. Pengenalan dan lokalisasi dipisahkan dengan presence head, yang meningkatkan akurasi deteksi. SAM 3 menggandakan akurasi sistem yang ada dalam PCS gambar dan video, serta meningkatkan kemampuan SAM sebelumnya pada tugas segmentasi visual. Kami membuka sumber SAM 3 bersama dengan benchmark baru kami, Segment Anything with Concepts (SA-Co), untuk segmentasi konsep yang dapat diprompt.

Model ini disumbangkan oleh yonigozlan dan ronghanghu.

Contoh penggunaan

Generasi Mask Otomatis dengan Pipeline

Sam3Tracker dapat digunakan untuk pembuatan maska otomatis guna memsegmentasi semua objek dalam gambar menggunakan pipeline mask-generation:

from transformers import pipeline


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

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

Segmentasi Gambar Dasar

Klik Titik Tunggal

Anda dapat memsegmentasi objek dengan memberikan satu kali klik pada objek yang ingin Anda segmentasi:

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

Beberapa Poin untuk Penyempurnaan

Anda dapat memberikan beberapa titik untuk menyempurnakan segmentasi:

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

Input Kotak Batas

Sam3Tracker juga mendukung input kotak pembatas untuk segmentasi:

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

Segmentasi Objek Ganda

Anda dapat memsegmentasikan beberapa objek secara bersamaan:

# 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

Inferensi Batch

Gambar Berbatch

Proses beberapa gambar secara bersamaan untuk efisiensi yang lebih baik:

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

Objek Batch per Gambar

Segmentasikan beberapa objek di dalam setiap gambar menggunakan inferensi batch:

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

Gambar Berbatch dengan Objek Berbatch dan Beberapa Titik

Atasi skenario batch kompleks dengan beberapa titik per objek:

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

Kotak Batas Berbatch

Proses beberapa gambar dengan input kotak pembatas:

# 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

Menggunakan Masker Sebelumnya sebagai Input

Sam3Tracker dapat menggunakan mask dari prediksi sebelumnya sebagai input untuk menyempurnakan segmentasi:

# 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

kelas transformers.Sam3TrackerConfig

< source >

Parameter

vision_config (Union[dict, ~configuration_utils.PreTrainedConfig], opsional) — Objek config atau dictionary dari vision backbone.
prompt_encoder_config (Union[dict, Sam3TrackerPromptEncoderConfig], opsional) — Kamus opsi konfigurasi yang digunakan untuk menginisialisasi Sam3TrackerPromptEncoderConfig.
mask_decoder_config (Union[dict, Sam3TrackerMaskDecoderConfig], opsional) — Kamus opsi konfigurasi yang digunakan untuk menginisialisasi Sam3TrackerMaskDecoderConfig.
initializer_range (float, opsional, defaultnya 0.02) — Standar deviasi dari truncated_normal_initializer untuk menginisialisasi semua matriks bobot.

Ini adalah kelas konfigurasi untuk menyimpan konfigurasi dari Sam3TrackerModel. Kelas ini digunakan untuk membuat model Sam3 Tracker berdasarkan argumen yang ditentukan, yang mendefinisikan arsitektur model. Membuat konfigurasi dengan nilai bawaan akan menghasilkan konfigurasi yang serupa dengan facebook/sam3

Objek konfigurasi mewarisi dari PreTrainedConfig dan dapat digunakan untuk mengontrol output model. Baca dokumentasi dari PreTrainedConfig untuk informasi lebih lanjut.

Contoh:

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

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

Parameter

hidden_size (int, opsional, default 256) — Dimensi dari representasi tersembunyi.
image_size (Union[int, list[int], tuple[int, int]], opsional, default 1008) — Ukuran (resolusi) dari setiap gambar.
patch_size (Union[int, list[int], tuple[int, int]], opsional, defaultnya 14) — Ukuran (resolusi) dari setiap patch.
mask_input_channels (int, opsional, default 16) — Jumlah channel yang akan diberikan ke modul MaskDecoder.
num_point_embeddings (int, opsional, defaultnya 4) — Jumlah point embeddings yang akan digunakan.
hidden_act (str, opsional, defaultnya gelu) — Fungsi aktivasi non-linear (fungsi atau string) di decoder. Misalnya, "gelu", "relu", "silu", dan sebagainya.
layer_norm_eps (float, opsional, defaultnya 1e-06) — Epsilon yang digunakan oleh lapisan normalisasi lapisan.
scale (float, opsional, default 1) — Faktor skala untuk prompt encoder.

Objek konfigurasi mewarisi dari PreTrainedConfig dan dapat digunakan untuk mengontrol output model. Baca dokumentasi dari PreTrainedConfig untuk informasi lebih lanjut.

Sam3TrackerMaskDecoderConfig

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

Parameter

hidden_size (int, opsional, default 256) — Dimensi dari representasi tersembunyi.
hidden_act (str, opsional, defaultnya gelu) — Fungsi aktivasi non-linear (fungsi atau string) di decoder. Misalnya, "gelu", "relu", "silu", dan sebagainya.
mlp_dim (int, opsional, default 2048) — Dimensi dari MLP dalam transformer dua arah.
num_hidden_layers (int, opsional, default 2) — Jumlah lapisan tersembunyi dalam decoder Transformer.
num_attention_heads (int, opsional, default 8) — Jumlah attention heads untuk setiap lapisan attention di decoder Transformer.
attention_downsample_rate (int, opsional, default 2) — Rasio downsample untuk lapisan attention.
num_multimask_outputs (int, opsional, defaultnya 3) — Jumlah output multimask.
iou_head_depth (int, opsional, defaultnya 3) — Kedalaman dari IoU head.
iou_head_hidden_dim (int, opsional, default 256) — Dimensi tersembunyi dari kepala IoU.
dynamic_multimask_via_stability (bool, opsional, defaultnya True) — Apakah akan menggunakan dynamic multimask via stability.
dynamic_multimask_stability_delta (float, opsional, default 0.05) — Delta stabilitas untuk dynamic multimask.
dynamic_multimask_stability_thresh (float, opsional, default 0.98) — Ambang batas stabilitas untuk dynamic multimask.

Objek konfigurasi mewarisi dari PreTrainedConfig dan dapat digunakan untuk mengontrol output model. Baca dokumentasi dari PreTrainedConfig untuk informasi lebih lanjut.

Sam3TrackerProcessor

kelas transformers.Sam3TrackerProcessor

< source >

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

Parameter

image_processor (Sam3ImageProcessor) — Image processor adalah input yang wajib diisi.
target_size (int, opsional) — Ukuran target (dalam piksel) untuk menormalisasi titik input dan kotak batas. Jika tidak disediakan, secara default menggunakan konfigurasi ukuran dari image processor. Semua koordinat input (titik dan kotak) dinormalisasi ke ukuran ini sebelum diteruskan ke model. Hal ini memastikan representasi koordinat yang konsisten terlepas dari dimensi gambar asli.
point_pad_value (int, opsional, default -10) — Nilai yang digunakan untuk mengisi titik input saat melakukan batching pada sekuens dengan panjang berbeda. Nilai ini digunakan untuk menandai posisi yang di-*pad* dan dipertahankan selama normalisasi koordinat.

Membangun Sam3TrackerProcessor yang membungkus image processor menjadi satu processor.

Sam3TrackerProcessor menyediakan semua fungsionalitas dari Sam3ImageProcessor. Lihat ~Sam3ImageProcessor untuk informasi lebih lanjut.

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

Parameter

images (Union[PIL.Image.Image, numpy.ndarray, torch.Tensor, list[PIL.Image.Image], list[numpy.ndarray], list[torch.Tensor]], opsional) — Gambar yang akan dipreprocess. Mengharapkan satu gambar atau batch gambar dengan nilai piksel berkisar dari 0 hingga 255. Jika mengirimkan gambar dengan nilai piksel antara 0 dan 1, atur do_rescale=False.
segmentation_maps (ImageInput, opsional) — Peta segmentasi yang akan diproses.
input_points (list[list[list[list[float]]]], torch.Tensor, opsional) — Titik-titik yang akan ditambahkan ke frame.
input_labels (list[list[list[int]]], torch.Tensor, opsional) — Label untuk titik-titik tersebut.
input_boxes (list[list[list[float]]], torch.Tensor, opsional) — Kotak pembatas (bounding boxes) yang akan ditambahkan ke bingkai.
original_sizes (list[list[float]], torch.Tensor, opsional) — Ukuran asli dari gambar-gambar tersebut.
return_tensors (Union[str, ~utils.generic.TensorType], opsional) — Jika diatur, akan mengembalikan tensor dari framework tertentu. Nilai yang dapat diterima adalah:
- 'pt': Mengembalikan objek PyTorch torch.Tensor.
- 'np': Mengembalikan objek NumPy np.ndarray.

Mengembalikan

BatchEncoding dengan field-field berikut

pixel_values (torch.Tensor): Gambar yang telah diproses.
original_sizes (list[list[float]]): Ukuran asli dari gambar-gambar tersebut.
labels (torch.Tensor): Peta segmentasi yang telah diproses (jika disediakan).
input_points (torch.Tensor): Titik-titik yang telah diproses.
input_labels (torch.Tensor): Label yang telah diproses.
input_boxes (torch.Tensor): Kotak pembatas yang telah diproses.

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)

Parameter

masks (Union[List[torch.Tensor], List[np.ndarray]]) — Mask yang di-batch dari mask_decoder dalam format (batch_size, num_channels, height, width).
original_sizes (Union[torch.Tensor, List[Tuple[int,int]]]) — Ukuran asli setiap gambar sebelum di-resize ke bentuk input yang diharapkan model, dalam format (tinggi, lebar).
mask_threshold (float, opsional, default 0.0) — Ambang batas untuk operasi binarisasi dan pascaproses.
binarize (bool, opsional, default True) — Apakah akan membinerisasi mask.
max_hole_area (float, opsional, default 0.0) — Luas maksimum lubang yang akan diisi.
max_sprinkle_area (float, opsional, default 0.0) — Area maksimum sprinkle yang akan diisi.
apply_non_overlapping_constraints (bool, opsional, default False) — Apakah akan menerapkan kendala non-overlapping pada mask.

Mengembalikan

(torch.Tensor)

Mask yang di-batch dalam format batch_size, num_channels, height, width, di mana (height, width) ditentukan oleh original_size.

Hapus padding dan upscale mask ke ukuran gambar asli.

Sam3TrackerModel

kelas transformers.Sam3TrackerModel

< source >

( config: Sam3TrackerConfig )

Parameter

config (Sam3TrackerConfig) — Kelas konfigurasi model dengan semua parameter model. Inisialisasi dengan file konfigurasi tidak memuat bobot yang terkait dengan model, hanya konfigurasinya. Lihat metode from_pretrained() untuk memuat bobot model.

Segment Anything Model 2 (SAM 2) untuk menghasilkan mask segmentasi, berdasarkan gambar input dan titik serta label, kotak, atau mask input.

Model ini mewarisi dari PreTrainedModel. Periksa dokumentasi kelas induk untuk metode generik yang diimplementasikan oleh pustaka untuk semua model (seperti mengunduh atau menyimpan, mengubah ukuran embedding input, memangkas kepala, dll.)

Model ini juga merupakan subclass dari torch.nn.Module PyTorch. Gunakan sebagai PyTorch Module biasa dan merujuk ke dokumentasi PyTorch untuk semua hal yang berkaitan dengan penggunaan dan perilaku umum.

forward

< source >

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

Parameter

pixel_values (torch.FloatTensor dengan bentuk (batch_size, num_channels, image_size, image_size), opsional) — Tensor yang sesuai dengan gambar input. Nilai piksel dapat diperoleh menggunakan Sam3ImageProcessor. Lihat Sam3ImageProcessor.call() untuk detailnya (Sam3TrackerProcessor menggunakan Sam3ImageProcessor untuk memproses gambar).
input_points (torch.FloatTensor dengan bentuk (batch_size, num_points, 2)) — Titik spasial 2D sebagai input, yang digunakan oleh prompt encoder untuk mengkodekan prompt. Umumnya menghasilkan hasil yang jauh lebih baik. Titik-titik ini dapat diperoleh dengan meneruskan daftar dari daftar dari daftar ke processor, yang akan membuat tensor torch yang sesuai dengan dimensi 4. Dimensi pertama adalah ukuran batch gambar, dimensi kedua adalah ukuran batch titik (yaitu berapa banyak mask segmentasi yang ingin diprediksi model per titik input), dimensi ketiga adalah jumlah titik per mask segmentasi (dimungkinkan untuk meneruskan beberapa titik untuk satu mask), dan dimensi terakhir adalah koordinat x (vertikal) dan y (horizontal) dari titik tersebut. Jika jumlah titik yang berbeda diteruskan baik untuk setiap gambar, maupun untuk setiap mask, processor akan membuat titik “PAD” yang akan sesuai dengan koordinat (0, 0), dan perhitungan embedding akan dilewati untuk titik-titik ini menggunakan label.
input_labels (torch.LongTensor dengan bentuk (batch_size, point_batch_size, num_points)) — Label input untuk titik-titik, yang digunakan oleh prompt encoder untuk meng-encode prompt. Menurut implementasi resmi, terdapat 3 jenis label
- 1: titik tersebut adalah titik yang berisi objek yang diminati
- 0: titik tersebut adalah titik yang tidak mengandung objek yang diminati
- -1: titik tersebut sesuai dengan latar belakang
Kami menambahkan label:
- -10: titik tersebut adalah titik padding, sehingga harus diabaikan oleh prompt encoder
Label padding seharusnya dilakukan secara otomatis oleh processor.
input_boxes (torch.FloatTensor dengan bentuk (batch_size, num_boxes, 4)) — kotak input untuk titik-titik, yang digunakan oleh prompt encoder untuk meng-encode prompt. Umumnya menghasilkan mask yang jauh lebih baik. Kotak-kotak ini dapat diperoleh dengan meneruskan list of list of list ke processor, yang akan menghasilkan torch tensor, dengan setiap dimensi yang masing-masing sesuai dengan ukuran batch gambar, jumlah kotak per gambar, dan koordinat titik kiri atas dan kanan bawah kotak. Dalam urutan (x1, y1, x2, y2):
- x1: koordinat x dari titik kiri atas kotak input
- y1: koordinat y dari titik kiri atas kotak input
- x2: koordinat x dari titik kanan bawah kotak input
- y2: koordinat y dari titik kanan bawah kotak input
input_masks (torch.FloatTensor dengan bentuk (batch_size, image_size, image_size)) — Model SAM juga menerima mask segmentasi sebagai input. Mask akan di-embed oleh prompt encoder untuk menghasilkan embedding yang sesuai, yang kemudian akan diberikan ke mask decoder. Mask ini perlu diberikan secara manual oleh pengguna, dan harus memiliki bentuk (batch_size, image_size, image_size).
image_embeddings (torch.FloatTensor dengan bentuk (batch_size, output_channels, window_size, window_size)) — Embedding gambar, yang digunakan oleh mask decoder untuk menghasilkan mask dan skor iou. Untuk komputasi yang lebih hemat memori, pengguna dapat terlebih dahulu mengambil embedding gambar menggunakan metode get_image_embeddings, lalu memasukkannya ke metode forward alih-alih memasukan pixel_values.
multimask_output (bool, opsional) — Pada implementasi dan paper aslinya, model selalu menghasilkan 3 mask per gambar (atau per titik / per bounding box jika relevan). Namun, dimungkinkan untuk hanya menghasilkan satu mask, yang sesuai dengan mask “terbaik”, dengan menentukan multimask_output=False.
attention_similarity (torch.FloatTensor, opsional) — Tensor kesamaan perhatian, yang akan diberikan ke decoder mask untuk perhatian yang dipandu target dalam kasus model digunakan untuk personalisasi sebagaimana diperkenalkan dalam PerSAM.
target_embedding (torch.FloatTensor, opsional) — Embedding dari konsep target, yang harus diberikan ke mask decoder untuk target-semantic prompting dalam kasus model digunakan untuk personalisasi sebagaimana diperkenalkan dalam PerSAM.

Mengembalikan

Sam3TrackerImageSegmentationOutput atau tuple(torch.FloatTensor)

Sam3TrackerImageSegmentationOutput atau tuple dari torch.FloatTensor (jika return_dict=False diteruskan atau ketika config.return_dict=False) yang terdiri dari berbagai elemen tergantung pada konfigurasi (Sam3TrackerConfig) dan input.

Metode forward dari Sam3TrackerModel menimpa metode khusus __call__.

Meskipun resep untuk forward pass perlu didefinisikan di dalam fungsi ini, sebaiknya panggil instance Module setelahnya alih-alih fungsi ini, karena yang pertama menangani langkah-langkah pra-pemrosesan dan pasca-pemrosesan, sedangkan yang kedua mengabaikannya secara diam-diam.

iou_scores (torch.FloatTensor dengan bentuk (batch_size, point_batch_size, num_masks)) — Skor Intersection over Union (IoU) dari mask yang diprediksi.
pred_masks (torch.FloatTensor dengan bentuk (batch_size, point_batch_size, num_masks, height, width)) — Mask beresolusi rendah yang diprediksi. Ini adalah alias untuk low_res_masks. Mask ini perlu diproses lebih lanjut oleh processor agar ukurannya sesuai dengan ukuran gambar asli.
object_score_logits (torch.FloatTensor dengan bentuk (batch_size, point_batch_size, 1)) — Logits untuk skor objek, yang menunjukkan apakah objek hadir.
image_embeddings (tuple(torch.FloatTensor)) — Fitur dari FPN yang digunakan oleh mask decoder. Ini adalah tuple dari torch.FloatTensor di mana setiap tensor memiliki bentuk (batch_size, channels, height, width).
vision_hidden_states (tuple(torch.FloatTensor), opsional, dikembalikan saat output_hidden_states=True) — Tuple dari torch.FloatTensor (satu untuk output dari setiap tahap) dengan bentuk (batch_size, height, width, hidden_size). Hidden-states dari model visi pada output dari setiap tahap.
vision_attentions (tuple(torch.FloatTensor), opsional, dikembalikan saat output_attentions=True) — Tuple dari torch.FloatTensor (satu untuk setiap lapisan) dengan bentuk (batch_size, num_heads, sequence_length, sequence_length). Bobot perhatian dari model visi.
mask_decoder_attentions (tuple(torch.FloatTensor), opsional, dikembalikan saat output_attentions=True) — Tuple dari torch.FloatTensor (satu untuk setiap layer) dengan bentuk (batch_size, num_heads, sequence_length, sequence_length). Bobot perhatian dari mask decoder.

Contoh:

>>> 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: FloatTensor**kwargs: *<class 'transformers.utils.generic.TransformersKwargs'> ) → Sam3TrackerVisionEncoderOutput or tuple(torch.FloatTensor)

Parameter

pixel_values (torch.FloatTensor) — Nilai piksel input dengan bentuk (batch_size, num_channels, height, width).

Mengembalikan

Sam3TrackerVisionEncoderOutput atau tuple(torch.FloatTensor)

A Sam3TrackerVisionEncoderOutput atau tuple dari torch.FloatTensor (jika return_dict=False diteruskan atau ketika config.return_dict=False) yang terdiri dari berbagai elemen tergantung pada konfigurasi (Sam3TrackerConfig) dan input.

last_hidden_state (torch.FloatTensor dengan bentuk (batch_size, height, width, hidden_size)) — Urutan hidden-states pada keluaran lapisan terakhir model.
pooler_output (torch.FloatTensor dengan bentuk (batch_size, hidden_size)) — State tersembunyi dari lapisan terakhir untuk token pertama dalam urutan (token klasifikasi) setelah diproses lebih lanjut melalui lapisan yang digunakan untuk tugas pra-pelatihan tambahan. Misalnya, untuk keluarga model BERT, ini mengembalikan token klasifikasi setelah diproses melalui lapisan linear dan fungsi aktivasi tanh. Bobot lapisan linear dilatih dari tujuan prediksi kalimat berikutnya (klasifikasi) selama pra-pelatihan.
hidden_states (tuple(torch.FloatTensor), opsional, dikembalikan saat output_hidden_states=True dilewatkan atau saat config.output_hidden_states=True) — Tuple dari torch.FloatTensor (satu untuk output dari embeddings, jika model memiliki lapisan embedding, + satu untuk output dari setiap lapisan) dengan bentuk (batch_size, sequence_length, hidden_size).

Hidden-states model pada output setiap layer ditambah output embedding awal yang opsional.
attentions (tuple(torch.FloatTensor), opsional, dikembalikan saat output_attentions=True dilewatkan atau saat config.output_attentions=True) — Tuple dari torch.FloatTensor (satu untuk setiap layer) dengan bentuk (batch_size, num_heads, sequence_length, sequence_length).

Bobot perhatian setelah softmax perhatian, digunakan untuk menghitung rata-rata berbobot di kepala perhatian diri (self-attention).
fpn_hidden_states (tuple(torch.FloatTensor)) — Tuple dari torch.FloatTensor (satu untuk setiap level fitur, dari resolusi tinggi ke rendah) dengan bentuk (batch_size, hidden_size, height, width). Peta fitur dari leher Feature Pyramid Network.
fpn_position_encoding (tuple(torch.FloatTensor)) — Tuple dari torch.FloatTensor (satu untuk setiap level fitur, dari resolusi tinggi ke rendah) dengan bentuk (batch_size, hidden_size, height, width). Encoding posisi yang sesuai dengan fpn_hidden_states.

Contoh:

Sam3TrackerPreTrainedModel

kelas transformers.Sam3TrackerPreTrainedModel

< source >

( config: PreTrainedConfig*inputs**kwargs )

Parameter

config (PreTrainedConfig) — Kelas konfigurasi model dengan semua parameter model. Inisialisasi dengan file konfigurasi tidak memuat bobot yang terkait dengan model, hanya konfigurasinya. Lihat metode from_pretrained() untuk memuat bobot model.

Segment Anything Model 3 (SAM 3) untuk menghasilkan mask segmentasi, berdasarkan gambar input serta titik dan label, kotak, atau mask input.

forward

( *args**kwargs )

Nilai mock untuk jalur bertitik (mis. torch.float32): rantai akses atribut, pemanggilan berperilaku sebagai dekorator pass-through, repr adalah jalur bertitik, dan penggunaannya sebagai kelas dasar menggantikan kelas dasar type polos (PEP 560 __mro_entries__), sehingga subkelas asli tetap mempertahankan metakelas normal dan inspect.signature membaca __init__ asli mereka, bukan milik mock.

Update on GitHub

←SAM2 Sapiens2→