Transformers documentation
Pelacak Video SAM3
Model ini disumbangkan ke Hugging Face Transformers pada 2025-11-19.
Pelacak Video SAM3
Ikhtisar
SAM3 (Segment Anything Model 3) diperkenalkan dalam SAM 3: Segment Anything with Concepts.
Sam3TrackerVideo melakukan Promptable Visual Segmentation (PVS) pada video. PVS menerima prompt visual interaktif (titik, kotak, mask) atau input teks untuk melacak instans objek tertentu per prompt di seluruh frame video.
Sam3TrackerVideo adalah versi pembaruan dari SAM2 Video 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
Segmentasi dan Pelacakan Video
Pelacakan Video Dasar
from transformers import Sam3TrackerVideoModel, Sam3TrackerVideoProcessor
import torch
model = Sam3TrackerVideoModel.from_pretrained("facebook/sam3", device_map="auto")
processor = Sam3TrackerVideoProcessor.from_pretrained("facebook/sam3")
# Load video frames (example assumes you have a list of PIL Images)
# video_frames = [Image.open(f"frame_{i:05d}.jpg") for i in range(num_frames)]
# For this example, we'll use the video loading utility
from transformers.video_utils import load_video
video_url = "https://huggingface.co/datasets/hf-internal-testing/sam2-fixtures/resolve/main/bedroom.mp4"
video_frames, _ = load_video(video_url)
# Initialize video inference session
inference_session = processor.init_video_session(
video=video_frames,
inference_device=device,
)
# Add click on first frame to select object
ann_frame_idx = 0
ann_obj_id = 1
points = [[[[210, 350]]]]
labels = [[[1]]]
processor.add_inputs_to_inference_session(
inference_session=inference_session,
frame_idx=ann_frame_idx,
obj_ids=ann_obj_id,
input_points=points,
input_labels=labels,
)
# Segment the object on the first frame (optional, you can also propagate the masks through the video directly)
outputs = model(
inference_session=inference_session,
frame_idx=ann_frame_idx,
)
video_res_masks = processor.post_process_masks(
[outputs.pred_masks], original_sizes=[[inference_session.video_height, inference_session.video_width]], binarize=False
)[0]
print(f"Segmentation shape: {video_res_masks.shape}")
Segmentation shape: torch.Size([1, 1, 480, 854])
# Propagate through the entire video
video_segments = {}
for sam3_tracker_video_output in model.propagate_in_video_iterator(inference_session):
video_res_masks = processor.post_process_masks(
[sam3_tracker_video_output.pred_masks], original_sizes=[[inference_session.video_height, inference_session.video_width]], binarize=False
)[0]
video_segments[sam3_tracker_video_output.frame_idx] = video_res_masks
print(f"Tracked object through {len(video_segments)} frames")
Tracked object through 180 framesPelacakan Video Multi-Objek
Lacak beberapa objek secara bersamaan di antara bingkai video:
# Reset for new tracking session
inference_session.reset_inference_session()
# Add multiple objects on the first frame
ann_frame_idx = 0
obj_ids = [2, 3]
input_points = [[[[200, 300]], [[400, 150]]]] # Points for two objects (batched)
input_labels = [[[1], [1]]]
processor.add_inputs_to_inference_session(
inference_session=inference_session,
frame_idx=ann_frame_idx,
obj_ids=obj_ids,
input_points=input_points,
input_labels=input_labels,
)
# Get masks for both objects on first frame (optional, you can also propagate the masks through the video directly)
outputs = model(
inference_session=inference_session,
frame_idx=ann_frame_idx,
)
# Propagate both objects through video
video_segments = {}
for sam3_tracker_video_output in model.propagate_in_video_iterator(inference_session):
video_res_masks = processor.post_process_masks(
[sam3_tracker_video_output.pred_masks], original_sizes=[[inference_session.video_height, inference_session.video_width]], binarize=False
)[0]
video_segments[sam3_tracker_video_output.frame_idx] = {
obj_id: video_res_masks[i]
for i, obj_id in enumerate(inference_session.obj_ids)
}
print(f"Tracked {len(inference_session.obj_ids)} objects through {len(video_segments)} frames")
Tracked 2 objects through 180 framesMenyempurnakan Segmentasi Video
Anda dapat menambahkan klik tambahan pada frame mana pun untuk menyempurnakan pelacakan:
# Add refinement click on a later frame
refine_frame_idx = 50
ann_obj_id = 2 # Refining first object
points = [[[[220, 280]]]] # Additional point
labels = [[[1]]] # Positive click
processor.add_inputs_to_inference_session(
inference_session=inference_session,
frame_idx=refine_frame_idx,
obj_ids=ann_obj_id,
input_points=points,
input_labels=labels,
)
# Re-propagate with the additional information
video_segments = {}
for sam3_tracker_video_output in model.propagate_in_video_iterator(inference_session):
video_res_masks = processor.post_process_masks(
[sam3_tracker_video_output.pred_masks], original_sizes=[[inference_session.video_height, inference_session.video_width]], binarize=False
)[0]
video_segments[sam3_tracker_video_output.frame_idx] = video_res_masksInferensi Video Streaming
Untuk aplikasi real-time, Sam3TrackerVideo mendukung pemrosesan bingkai video saat bingkai tersebut tiba:
# Initialize session for streaming
inference_session = processor.init_video_session(
inference_device=device,
)
# Process frames one by one
for frame_idx, frame in enumerate(video_frames[:10]): # Process first 10 frames
inputs = processor(images=frame, device=device, return_tensors="pt").to(model.device)
...
if frame_idx == 0:
# Add point input on first frame
processor.add_inputs_to_inference_session(
inference_session=inference_session,
frame_idx=0,
obj_ids=1,
input_points=[[[[210, 350], [250, 220]]]],
input_labels=[[[1, 1]]],
original_size=inputs.original_sizes[0], # need to be provided when using streaming video inference
)
...
# Process current frame
sam3_tracker_video_output = model(inference_session=inference_session, frame=inputs.pixel_values[0])
...
video_res_masks = processor.post_process_masks(
[sam3_tracker_video_output.pred_masks], original_sizes=inputs.original_sizes, binarize=False
)[0]
print(f"Frame {frame_idx}: mask shape {video_res_masks.shape}")Pemrosesan Batch Video untuk Beberapa Objek
Lacak beberapa objek secara bersamaan dalam video dengan menambahkan semuanya sekaligus:
# Initialize video session
inference_session = processor.init_video_session(
video=video_frames,
inference_device=device,
)
# Add multiple objects on the first frame using batch processing
ann_frame_idx = 0
obj_ids = [2, 3] # Track two different objects
input_points = [
[[[200, 300], [230, 250], [275, 175]], [[400, 150]]]
] # Object 2: 3 points (2 positive, 1 negative); Object 3: 1 point
input_labels = [
[[1, 1, 0], [1]]
] # Object 2: positive, positive, negative; Object 3: positive
processor.add_inputs_to_inference_session(
inference_session=inference_session,
frame_idx=ann_frame_idx,
obj_ids=obj_ids,
input_points=input_points,
input_labels=input_labels,
)
# Get masks for all objects on the first frame
outputs = model(
inference_session=inference_session,
frame_idx=ann_frame_idx,
)
video_res_masks = processor.post_process_masks(
[outputs.pred_masks], original_sizes=[[inference_session.video_height, inference_session.video_width]], binarize=False
)[0]
print(f"Generated masks for {video_res_masks.shape[0]} objects")
Generated masks for 2 objects
# Propagate all objects through the video
video_segments = {}
for sam3_tracker_video_output in model.propagate_in_video_iterator(inference_session):
video_res_masks = processor.post_process_masks(
[sam3_tracker_video_output.pred_masks], original_sizes=[[inference_session.video_height, inference_session.video_width]], binarize=False
)[0]
video_segments[sam3_tracker_video_output.frame_idx] = {
obj_id: video_res_masks[i]
for i, obj_id in enumerate(inference_session.obj_ids)
}
print(f"Tracked {len(inference_session.obj_ids)} objects through {len(video_segments)} frames")
Tracked 2 objects through 180 framesSam3TrackerVideoConfig
kelas transformers.Sam3TrackerVideoConfig
< 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.02num_maskmem: int = 7sigmoid_scale_for_mem_enc: float = 20.0sigmoid_bias_for_mem_enc: float = -10.0enable_occlusion_spatial_embedding: bool = Truemultimask_output_in_sam: bool = Truemultimask_min_pt_num: int = 0multimask_max_pt_num: int = 1multimask_output_for_tracking: bool = Truemax_object_pointers_in_encoder: int = 16max_cond_frame_num: int = 4enable_temporal_pos_encoding_for_object_pointers: bool = Truememory_attention_hidden_size: int = 256memory_attention_num_layers: int = 4memory_attention_num_attention_heads: int = 1memory_attention_downsample_rate: int = 1memory_attention_feed_forward_hidden_size: int = 2048memory_attention_feed_forward_hidden_act: str = 'relu'memory_attention_dropout: float | int = 0.1memory_attention_rope_feat_sizes: list | None = Nonememory_attention_rope_dropout: float | int = 0.1memory_encoder_hidden_size: int = 256memory_encoder_output_channels: int = 64rope_parameters: dict | None = Nonemask_downsampler_embed_dim: int = 256mask_downsampler_kernel_size: int = 3mask_downsampler_stride: int = 2mask_downsampler_padding: int = 1mask_downsampler_total_stride: int = 16mask_downsampler_hidden_act: str = 'gelu'memory_fuser_num_layers: int = 2memory_fuser_embed_dim: int = 256memory_fuser_intermediate_dim: int = 1024memory_fuser_kernel_size: int = 7memory_fuser_padding: int = 3memory_fuser_layer_scale_init_value: float = 1e-06memory_fuser_hidden_act: str = 'gelu' )
Parameter
- vision_config (
Union[dict, ~configuration_utils.PreTrainedConfig], opsional) — Objek config atau dictionary dari vision backbone. - prompt_encoder_config (Union[
dict,Sam3TrackerVideoPromptEncoderConfig], opsional) — Kamus opsi konfigurasi yang digunakan untuk menginisialisasi Sam3TrackerVideoPromptEncoderConfig. - mask_decoder_config (Union[
dict,Sam3TrackerVideoMaskDecoderConfig], opsional) — Kamus opsi konfigurasi yang digunakan untuk menginisialisasi Sam3TrackerVideoMaskDecoderConfig. - initializer_range (
float, opsional, default 0.02) — Deviasi standar untuk inisialisasi parameter. - num_maskmem (
int, opsional, defaultnya 7) — Jumlah slot memori untuk memori mask. - sigmoid_scale_for_mem_enc (
float, opsional, default 20.0) — Faktor skala untuk fungsi sigmoid dalam memory encoder. - sigmoid_bias_for_mem_enc (
float, opsional, default -10.0) — Bias untuk fungsi sigmoid dalam memory encoder. - enable_occlusion_spatial_embedding (
bool, opsional, defaultTrue) — Apakah akan mengaktifkan spatial embedding untuk oklusi. - multimask_output_in_sam (
bool, opsional, defaultTrue) — Apakah akan mengoutputkan beberapa mask dari head SAM. - multimask_min_pt_num (
int, opsional, default 0) — Jumlah minimum titik untuk memicu output multimask. - multimask_max_pt_num (
int, opsional, default 1) — Jumlah maksimum titik untuk memicu output multimask. - multimask_output_for_tracking (
bool, opsional, defaultnyaTrue) — Apakah akan menggunakan output multimask untuk pelacakan. - max_object_pointers_in_encoder (
int, opsional, defaultnya 16) — Jumlah maksimum pointer objek dalam encoder. - max_cond_frame_num (
int, opsional, default 4) — Jumlah maksimum frame kondisioning yang digunakan dalam memori perhatian. - enable_temporal_pos_encoding_for_object_pointers (
bool, opsional, defaultTrue) — Apakah akan mengaktifkan temporal positional encoding untuk object pointers. - memory_attention_hidden_size (
int, opsional, default 256) — Dimensi dari hidden states memori attention. - memory_attention_num_layers (
int, opsional, default 4) — Jumlah lapisan dalam modul memory attention. - memory_attention_num_attention_heads (
int, opsional, default 1) — Jumlah attention head untuk setiap lapisan attention dalam memory attention. - memory_attention_downsample_rate (
int, opsional, default 1) — Laju downsample untuk lapisan attention. - memory_attention_feed_forward_hidden_size (
int, opsional, default 2048) — Dimensi dari jaringan feedforward dalam modul memory attention. - memory_attention_feed_forward_hidden_act (
str, opsional, default"relu") — Fungsi aktivasi non-linear pada jaringan feedforward di dalam modul memory attention. - memory_attention_dropout (
float, opsional, default 0.1) — Tingkat dropout untuk modul memory attention. - memory_attention_rope_feat_sizes (
list[int], opsional, default[72, 72]) — Ukuran fitur untuk encoding posisi Rope. - memory_attention_rope_dropout (
float, opsional, default 0.1) — Tingkat dropout untuk pengkodean posisi Rope. - memory_encoder_hidden_size (
int, opsional, default 256) — Dimensi dari hidden states memory encoder. - memory_encoder_output_channels (
int, opsional, defaultnya 64) — Jumlah saluran keluar untuk memory encoder. - rope_parameters (
dict, opsional) — Kamus yang berisi parameter konfigurasi untuk embedding RoPE. Kamus tersebut harus berisi nilai untukrope_thetadan secara opsional parameter yang digunakan untuk penskalaan jika Anda ingin menggunakan RoPE denganmax_position_embeddingsyang lebih panjang. - mask_downsampler_embed_dim (
int, opsional, default 256) — Dimensi dari embedding mask downsampler. - mask_downsampler_kernel_size (
int, opsional, default 3) — Ukuran kernel untuk downsampler mask. - mask_downsampler_stride (
int, opsional, defaultnya 2) — Stride untuk mask downsampler. - mask_downsampler_padding (
int, opsional, defaultnya 1) — Padding untuk mask downsampler. - mask_downsampler_total_stride (
int, opsional, default 16) — Stride total untuk mask downsampler. - mask_downsampler_hidden_act (
str, opsional, defaultnya"gelu") — Fungsi aktivasi non-linear pada mask downsampler. - memory_fuser_num_layers (
int, opsional, defaultnya 2) — Jumlah lapisan dalam memory fuser. - memory_fuser_embed_dim (
int, opsional, default 256) — Dimensi dari lapisan embedding di memory fuser. - memory_fuser_intermediate_dim (
int, opsional, default 1024) — Dimensi dari lapisan perantara dalam memory fuser. - memory_fuser_kernel_size (
int, opsional, defaultnya 7) — Ukuran kernel untuk memory fuser. - memory_fuser_padding (
int, opsional, defaultnya 3) — Padding untuk memory fuser. - memory_fuser_layer_scale_init_value (
float, opsional, default 1e-06) — Nilai awal untuk skala layer dalam memory fuser. - memory_fuser_hidden_act (
str, opsional, default"gelu") — Fungsi aktivasi non-linear dalam memory fuser.
Ini adalah kelas konfigurasi untuk menyimpan konfigurasi dari Sam3TrackerVideoModel. Kelas ini digunakan untuk membuat instans model Sam3 Tracker Video berdasarkan argumen yang ditentukan, yang mendefinisikan arsitektur model. Membuat instans konfigurasi dengan nilai bawaan akan menghasilkan konfigurasi yang serupa dengan konfigurasi dari 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 (
... Sam3VisionConfig,
... Sam3TrackerVideoPromptEncoderConfig,
... Sam3TrackerVideoMaskDecoderConfig,
... Sam3TrackerVideoModel,
... )
>>> # Initializing a Sam3TrackerVideoConfig with `"facebook/sam3"` style configuration
>>> configuration = Sam3TrackerVideoConfig()
>>> # Initializing a Sam3TrackerVideoModel (with random weights) from the `"facebook/sam3"` style configuration
>>> model = Sam3TrackerVideoModel(configuration)
>>> # Accessing the model configuration
>>> configuration = model.config
>>> # We can also initialize a Sam3TrackerVideoConfig from a Sam3TrackerVideoVisionConfig, Sam3TrackerVideoPromptEncoderConfig, and Sam3TrackerVideoMaskDecoderConfig
>>> # Initializing SAM3 tracker video vision encoder, memory attention, and memory encoder configurations
>>> vision_config = Sam3TrackerVideoVisionConfig()
>>> prompt_encoder_config = Sam3TrackerVideoPromptEncoderConfig()
>>> mask_decoder_config = Sam3TrackerVideoMaskDecoderConfig()
>>> config = Sam3TrackerVideoConfig(vision_config, prompt_encoder_config, mask_decoder_config)Sam3TrackerVideoMaskDecoderConfig
kelas transformers.Sam3TrackerVideoMaskDecoderConfig
< 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, default256) — Dimensi dari representasi tersembunyi. - hidden_act (
str, opsional, defaultnyagelu) — 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, default2) — Jumlah lapisan tersembunyi dalam decoder Transformer. - num_attention_heads (
int, opsional, default8) — 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, defaultnyaTrue) — 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.
Ini adalah kelas konfigurasi untuk menyimpan konfigurasi dari Sam3TrackerVideoModel. Kelas ini digunakan untuk membuat instans model Sam3 Tracker Video berdasarkan argumen yang ditentukan, yang mendefinisikan arsitektur model. Membuat instans konfigurasi dengan nilai bawaan akan menghasilkan konfigurasi yang serupa dengan konfigurasi dari facebook/sam3
Objek konfigurasi mewarisi dari PreTrainedConfig dan dapat digunakan untuk mengontrol output model. Baca dokumentasi dari PreTrainedConfig untuk informasi lebih lanjut.
Sam3TrackerVideoPromptEncoderConfig
kelas transformers.Sam3TrackerVideoPromptEncoderConfig
< 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, default256) — Dimensi dari representasi tersembunyi. - image_size (
Union[int, list[int], tuple[int, int]], opsional, default1008) — Ukuran (resolusi) dari setiap gambar. - patch_size (
Union[int, list[int], tuple[int, int]], opsional, defaultnya14) — Ukuran (resolusi) dari setiap patch. - mask_input_channels (
int, opsional, default 16) — Jumlah channel yang akan diberikan ke modulMaskDecoder. - num_point_embeddings (
int, opsional, defaultnya 4) — Jumlah point embeddings yang akan digunakan. - hidden_act (
str, opsional, defaultnyagelu) — Fungsi aktivasi non-linear (fungsi atau string) di decoder. Misalnya,"gelu","relu","silu", dan sebagainya. - layer_norm_eps (
float, opsional, defaultnya1e-06) — Epsilon yang digunakan oleh lapisan normalisasi lapisan. - scale (
float, opsional, default 1) — Faktor skala untuk prompt encoder.
Ini adalah kelas konfigurasi untuk menyimpan konfigurasi dari Sam3TrackerVideoModel. Kelas ini digunakan untuk membuat instans model Sam3 Tracker Video berdasarkan argumen yang ditentukan, yang mendefinisikan arsitektur model. Membuat instans konfigurasi dengan nilai bawaan akan menghasilkan konfigurasi yang serupa dengan konfigurasi dari facebook/sam3
Objek konfigurasi mewarisi dari PreTrainedConfig dan dapat digunakan untuk mengontrol output model. Baca dokumentasi dari PreTrainedConfig untuk informasi lebih lanjut.
Sam3TrackerVideoProcessor
kelas transformers.Sam3TrackerVideoProcessor
< source >( image_processorvideo_processortarget_size: int | None = Nonepoint_pad_value: int = -10**kwargs )
Parameter
- image_processor (
Sam3ImageProcessor) — Image processor adalah input yang wajib diisi. - video_processor (
video_processor_class) — Video 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 Sam3TrackerVideoProcessor yang membungkus image processor dan video processor menjadi satu processor tunggal.
Sam3TrackerVideoProcessor menyediakan semua fungsionalitas dari Sam3ImageProcessor dan video_processor_class. Lihat ~Sam3ImageProcessor dan ~video_processor_class 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, aturdo_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 PyTorchtorch.Tensor.'np': Mengembalikan objek NumPynp.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, defaultTrue) — 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, defaultFalse) — 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.
init_video_session
< source >( video: typing.Union[list['PIL.Image.Image'], numpy.ndarray, ForwardRef('torch.Tensor'), list[numpy.ndarray], list['torch.Tensor'], list[list['PIL.Image.Image']], list[list[numpy.ndarray]], list[list['torch.Tensor']], transformers.video_utils.URL, list[transformers.video_utils.URL], list[list[transformers.video_utils.URL]], transformers.video_utils.Path, list[transformers.video_utils.Path], list[list[transformers.video_utils.Path]], NoneType] = Noneinference_device: typing.Union[str, ForwardRef('torch.device')] = 'cpu'inference_state_device: typing.Union[str, ForwardRef('torch.device'), NoneType] = Noneprocessing_device: typing.Union[str, ForwardRef('torch.device'), NoneType] = Nonevideo_storage_device: typing.Union[str, ForwardRef('torch.device'), NoneType] = Nonemax_vision_features_cache_size: int = 1dtype: dtype = torch.float32 )
Parameter
- video (
VideoInput, opsional) — Video yang akan diproses. Tidak perlu disediakan saat streaming. - inference_device (
stratautorch.device, opsional, default “cpu”) — Perangkat yang akan digunakan untuk inferensi. - inference_state_device (
stratautorch.device, opsional) — Perangkat untuk menyimpan state inferensi. - processing_device (
stratautorch.device, opsional) — Perangkat yang akan digunakan untuk pemrosesan video. - video_storage_device (
stratautorch.device, opsional) — Perangkat untuk menyimpan bingkai video yang telah diproses. - max_vision_features_cache_size (
int, opsional, default 1) — Jumlah maksimum fitur visual yang akan di-cache. - dtype (
torch.dtype, opsional, defaulttorch.float32) — torch dtype yang digunakan untuk seluruh sesi.
Menginisialisasi sesi video untuk inferensi.
Jika video disediakan (inferensi asinkron), video tersebut akan diproses dan disimpan di video_storage_device.
add_inputs_to_inference_session
< source >( inference_session: Sam3TrackerVideoInferenceSessionframe_idx: intobj_ids: list[int] | intinput_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] = Noneinput_masks: typing.Union[numpy.ndarray, torch.Tensor, list[numpy.ndarray], list[torch.Tensor], NoneType] = Noneoriginal_size: tuple[int, int] | None = Noneclear_old_inputs: bool = True )
Parameter
- inference_session (
Sam3TrackerVideoInferenceSession) — Sesi inferensi untuk video. - frame_idx (
int) — Indeks frame yang akan diproses. - obj_ids (
list[int]atauint) — ID objek yang akan dikaitkan dengan titik atau kotak. Nilai ini dapat berupa bilangan bulat apa pun dan dapat digunakan kembali di kemudian hari untuk menentukan sebuah objek. - 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. - input_masks (
np.ndarray,torch.Tensor,list[np.ndarray], ataulist[torch.Tensor], opsional) — Masker yang akan ditambahkan ke frame. - original_size (
tuple[int, int], opsional) — Ukuran asli video. Sediakan saat streaming. - clear_old_inputs (
bool, opsional, defaultTrue) — Apakah akan menghapus input lama untuk objek tersebut.
Proses titik, kotak, atau mask baru untuk bingkai video dan tambahkan ke sesi inferensi.
Sam3TrackerVideoInferenceSession
kelas transformers.Sam3TrackerVideoInferenceSession
< source >( video: typing.Optional[torch.Tensor] = Nonevideo_height: int | None = Nonevideo_width: int | None = Noneinference_device: typing.Union[torch.device, str] = 'cpu'inference_state_device: typing.Union[torch.device, str] = 'cpu'video_storage_device: typing.Union[torch.device, str] = 'cpu'dtype: typing.Union[torch.dtype, str] = 'float32'max_vision_features_cache_size: int = 1 )
Parameter
- video (
torch.Tensor, opsional) — Video yang akan diproses. Tidak perlu disediakan saat streaming. - video_height (
int, opsional) — Tinggi video. - video_width (
int, opsional) — Lebar video. - inference_device (
torch.device, opsional, default"cpu") — Perangkat yang digunakan untuk inferensi. - inference_state_device (
torch.device, opsional, default"cpu") — Perangkat untuk menyimpan state inferensi. - video_storage_device (
torch.device, opsional, default"cpu") — Perangkat untuk menyimpan video. - dtype (
torch.dtype, opsional, defaultnya"float32") — dtype yang akan digunakan untuk video. - max_vision_features_cache_size (
int, opsional, default 1) — Jumlah maksimum fitur visual yang akan di-cache.
Mengelola parameter, status, dan cache sesi inferensi video.
Tambahkan input mask dengan penempatan perangkat otomatis.
Tambahkan frame baru dengan penempatan perangkat otomatis.
Tambahkan input titik dengan penempatan perangkat otomatis.
Ambil frame dari video.
Dapatkan jumlah total id objek unik yang diterima sejauh ini dalam sesi ini.
get_output
< source >( obj_idx: intframe_idx: intoutput_key: stris_conditioning_frame: bool = True )
Dapatkan output dengan manajemen perangkat pintar.
Petakan ID objek ke indeks, buat entri baru jika diperlukan.
Petakan indeks objek sisi model ke id objek sisi klien.
Hapus input mask.
Hapus input titik.
Reset data pelacakan dan cache.
Reset data pelacakan tetapi pertahankan cache.
store_output
< source >( obj_idx: intframe_idx: intoutput_key: str | None = Noneoutput_value: typing.Union[torch.Tensor, dict, NoneType] = Noneis_conditioning_frame: bool = True )
Parameter
- obj_idx (int) — Indeks dari objek.
- frame_idx (int) — Indeks dari frame.
- output_key (Optional[str]) — Kunci dari output. Jika None, output disimpan sebagai kamus.
- output_value (Optional[Union[torch.Tensor, dict]]) — Nilai dari output.
- is_conditioning_frame (bool) — Apakah output tersebut untuk frame conditioning.
Simpan output dengan manajemen perangkat yang cerdas. Jika output_key adalah None, output disimpan sebagai kamus.
Sam3TrackerVideoModel
kelas transformers.Sam3TrackerVideoModel
< source >( config: Sam3TrackerVideoConfigremove_vision_encoder: bool = False )
Parameter
- config (Sam3TrackerVideoConfig) — 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.
- remove_vision_encoder (
bool, opsional, defaultFalse) — Apakah akan menghapus vision encoder. Jika True, vision encoder akan diset ke None.
Model Pelacak Video Sam3 polos yang menghasilkan hidden-states mentah tanpa head spesifik di atasnya.
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 >( inference_session: Sam3TrackerVideoInferenceSessionframe_idx: int | None = Noneframe: typing.Optional[torch.Tensor] = Nonereverse: bool = Falserun_mem_encoder: bool = True**kwargs ) → Sam3TrackerVideoSegmentationOutput or tuple(torch.Tensor)
Parameter
- inference_session (
~models.sam3_tracker_video.modeling_sam3_tracker_video.Sam3TrackerVideoInferenceSession) — Objek sesi inferensi video. - frame_idx (
int, opsional) — Indeks frame tempat inferensi dijalankan. Tidak perlu disediakan saat melakukan inferensi pada frame streaming baru. - frame (
torch.Tensor, opsional) — Frame yang akan diproses. Berikan saat streaming. - reverse (
bool, opsional, defaultFalse) — Apakah akan melakukan propagasi secara terbalik. - run_mem_encoder (
bool, opsional, defaultTrue) — Apakah akan menjalankan memory encoder pada mask yang diprediksi. Memory encoder di-batch untuk semua objek demi efisiensi.
Mengembalikan
Sam3TrackerVideoSegmentationOutput atau tuple(torch.Tensor)
Sam3TrackerVideoSegmentationOutput atau tuple dari
torch.Tensor (jika return_dict=False dilewatkan atau ketika config.return_dict=False) yang terdiri dari berbagai
elemen tergantung pada konfigurasi (Sam3TrackerVideoConfig) dan input.
Propagasi objek melalui bingkai video yang dialirkan.
- object_ids (
list[int], opsional) — Daftar ID objek yang dilacak pada frame saat ini. - pred_masks (
torch.Tensordengan bentuk(batch_size, num_masks, height, width)) — Mask yang diprediksi dan disimpan pada resolusi model. - object_score_logits (
torch.Tensordengan bentuk(batch_size,), opsional) — Logits untuk skor objek, yang menunjukkan apakah objek hadir. - frame_idx (
int, opsional) — Indeks frame dari video.
propagate_in_video_iterator
< source >( inference_session: Sam3TrackerVideoInferenceSessionstart_frame_idx: int | None = Nonemax_frame_num_to_track: int | None = Nonereverse: bool = Falseshow_progress_bar: bool = False ) → Sam3TrackerVideoSegmentationOutput or tuple(torch.Tensor)
Parameter
- inference_session (
~models.sam3_tracker_video.modeling_sam3_tracker_video.Sam3TrackerVideoInferenceSession) — Objek sesi inferensi video. - start_frame_idx (
int, opsional) — Indeks frame awal untuk propagasi. Harus disediakan jikaforwardbelum dipanggil pada input baru. Jika tidak disediakan, indeks frame awal akan menjadi frame terawal yang memiliki titik input. - max_frame_num_to_track (
int, opsional) — Jumlah maksimum frame yang akan dilacak. - reverse (
bool, opsional, defaultFalse) — Apakah akan melakukan propagasi secara terbalik. - show_progress_bar (
bool, opsional, defaultFalse) — Apakah menampilkan progress bar selama propagasi.
Mengembalikan
Sam3TrackerVideoSegmentationOutput atau tuple(torch.Tensor)
Sam3TrackerVideoSegmentationOutput atau tuple dari
torch.Tensor (jika return_dict=False dilewatkan atau ketika config.return_dict=False) yang terdiri dari berbagai
elemen tergantung pada konfigurasi (Sam3TrackerVideoConfig) dan input.
Propagasi objek melalui bingkai video. Digunakan saat menginisialisasi sesi inferensi dengan video utuh. Menghasilkan Sam3TrackerVideoSegmentationOutput untuk setiap bingkai.
- object_ids (
list[int], opsional) — Daftar ID objek yang dilacak pada frame saat ini. - pred_masks (
torch.Tensordengan bentuk(batch_size, num_masks, height, width)) — Mask yang diprediksi dan disimpan pada resolusi model. - object_score_logits (
torch.Tensordengan bentuk(batch_size,), opsional) — Logits untuk skor objek, yang menunjukkan apakah objek hadir. - frame_idx (
int, opsional) — Indeks frame dari video.
get_image_features
< source >( pixel_values: Tensor**kwargs: *<class 'transformers.utils.generic.TransformersKwargs'> ) → Sam3TrackerVideoVisionEncoderOutput or tuple(torch.Tensor)
Parameter
- pixel_values (
torch.Tensor) — Nilai piksel input dengan bentuk(batch_size, num_channels, height, width).
Mengembalikan
Sam3TrackerVideoVisionEncoderOutput atau tuple(torch.Tensor)
Sam3TrackerVideoVisionEncoderOutput atau tuple dari
torch.Tensor (jika return_dict=False diteruskan atau ketika config.return_dict=False) yang terdiri dari berbagai
elemen tergantung pada konfigurasi (Sam3TrackerVideoConfig) dan input.
last_hidden_state (
torch.Tensordengan bentuk(batch_size, height, width, hidden_size)) — Urutan hidden-states pada output dari lapisan terakhir model.pooler_output (
torch.Tensordengan bentuk(batch_size, hidden_size)) — Hidden-state lapisan terakhir dari 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.Tensor), opsional, dikembalikan saatoutput_hidden_states=Truedilewatkan atau saatconfig.output_hidden_states=True) — Tuple daritorch.Tensor(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.Tensor), opsional, dikembalikan saatoutput_attentions=Truedilewatkan atau saatconfig.output_attentions=True) — Tuple daritorch.Tensor(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.Tensor)) — Tuple daritorch.Tensor(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.Tensor)) — Tuple daritorch.Tensor(satu untuk setiap level fitur, dari resolusi tinggi ke rendah) dengan bentuk(batch_size, hidden_size, height, width). Encoding posisi yang sesuai denganfpn_hidden_states.