# SAM3 Video

    
        
        
    

## Ikhtisar

SAM3 (Segment Anything Model 3) diperkenalkan dalam [SAM 3: Segment Anything with Concepts](https://ai.meta.com/research/publications/sam-3-segment-anything-with-concepts/).

SAM3 Video melakukan **Promptable Concept Segmentation (PCS)** pada video. PCS menerima teks sebagai input (misalnya, "yellow school bus"), dan memprediksi mask instance dan semantik untuk **setiap objek** yang cocok dengan konsep tersebut, sambil mempertahankan identitas objek di seluruh frame video.

Model ini menggabungkan modul deteksi (SAM3) dengan modul pelacakan (pelacak bergaya SAM2) untuk memungkinkan pelacakan objek yang andal di antara bingkai video menggunakan prompt teks.

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) mengambil 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](https://huggingface.co/yonigozlan) dan [ronghanghu](https://huggingface.co/ronghanghu).

## Contoh penggunaan

### Segmentasi dan Pelacakan Video

#### Inferensi Video Pra-muat

Proses video dengan semua frame yang sudah tersedia menggunakan prompt teks:

```python
from transformers import Sam3VideoModel, Sam3VideoProcessor
import torch

model = Sam3VideoModel.from_pretrained("facebook/sam3", device_map="auto")
processor = Sam3VideoProcessor.from_pretrained("facebook/sam3")

# Load video frames
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,
    processing_device="cpu",
    video_storage_device="cpu",
)

# Add text prompt to detect and track objects
text = "person"
inference_session = processor.add_text_prompt(
    inference_session=inference_session,
    text=text,
)

# Process all frames in the video
outputs_per_frame = {}
# Pass show_progress_bar=True to display a tqdm progress bar.
for model_outputs in model.propagate_in_video_iterator(
    inference_session=inference_session, max_frame_num_to_track=50
):
    processed_outputs = processor.postprocess_outputs(inference_session, model_outputs)
    outputs_per_frame[model_outputs.frame_idx] = processed_outputs

print(f"Processed {len(outputs_per_frame)} frames")
Processed 51 frames

# Access results for a specific frame
frame_0_outputs = outputs_per_frame[0]
print(f"Detected {len(frame_0_outputs['object_ids'])} objects")
print(f"Object IDs: {frame_0_outputs['object_ids'].tolist()}")
print(f"Scores: {frame_0_outputs['scores'].tolist()}")
print(f"Boxes shape (XYXY format, absolute coordinates): {frame_0_outputs['boxes'].shape}")
print(f"Masks shape: {frame_0_outputs['masks'].shape}")
```

Anda juga dapat melacak beberapa kategori objek secara bersamaan dengan menyediakan beberapa prompt. Model ini secara efisien menggunakan ulang fitur visual di semua prompt:

```python
# Add multiple text prompts (or use a list in add_text_prompt)
multi_prompt_session = processor.init_video_session(
    video=video_frames,
    inference_device=device,
    processing_device="cpu",
    video_storage_device="cpu",
)
>>>
prompts = ["person", "bed", "lamp"]
processor.add_text_prompt(multi_prompt_session, prompts)
>>>
# Process video - detects objects from ALL prompts in a single pass
multi_outputs_per_frame = {}
# Pass show_progress_bar=True to display a tqdm progress bar.
for model_outputs in model.propagate_in_video_iterator(
    inference_session=multi_prompt_session, max_frame_num_to_track=50
):
    processed_outputs = processor.postprocess_outputs(multi_prompt_session, model_outputs)
    multi_outputs_per_frame[model_outputs.frame_idx] = processed_outputs
>>>
# Check which objects were detected by each prompt
frame_0_outputs = multi_outputs_per_frame[0]
prompt_to_obj_ids = frame_0_outputs["prompt_to_obj_ids"]
for prompt, obj_ids in prompt_to_obj_ids.items():
    print(f"{prompt}: {len(obj_ids)} objects")
person: 2 objects
bed: 1 objects
lamp: 1 objects
```

#### Inferensi Video Streaming

⚠️ **Catatan tentang Kualitas Inferensi Streaming**: Inferensi streaming menonaktifkan heuristik hotstart yang menghapus objek yang tidak cocok dan duplikat, karena heuristik tersebut memerlukan akses ke frame di masa depan untuk membuat keputusan yang tepat. Hal ini dapat menghasilkan lebih banyak deteksi positif palsu dan track objek duplikat dibandingkan dengan inferensi video yang dimuat sebelumnya. Untuk hasil terbaik, gunakan inferensi video yang dimuat sebelumnya ketika semua frame tersedia.

Untuk aplikasi real-time, SAM3 Video mendukung pemrosesan bingkai video saat bingkai tersebut tiba:

```python
# Initialize session for streaming
streaming_inference_session = processor.init_video_session(
    inference_device=device,
    processing_device="cpu",
    video_storage_device="cpu",
)

# Add text prompt
text = "person"
streaming_inference_session = processor.add_text_prompt(
    inference_session=streaming_inference_session,
    text=text,
)

# Process frames one by one (streaming mode)
streaming_outputs_per_frame = {}
for frame_idx, frame in enumerate(video_frames[:50]):  # Process first 50 frames
    # First, process the frame using the processor
    inputs = processor(images=frame, device=device, return_tensors="pt").to(model.device)
...
    # Process frame using streaming inference - pass the processed pixel_values
    model_outputs = model(
        inference_session=streaming_inference_session,
        frame=inputs.pixel_values[0],  # Provide processed frame - this enables streaming mode
        reverse=False,
    )
...
    # Post-process outputs with original_sizes for proper resolution handling
    processed_outputs = processor.postprocess_outputs(
        streaming_inference_session,
        model_outputs,
        original_sizes=inputs.original_sizes,  # Required for streaming inference
    )
    streaming_outputs_per_frame[frame_idx] = processed_outputs
...
    if (frame_idx + 1) % 10 == 0:
        print(f"Processed {frame_idx + 1} frames...")

print(f"✓ Streaming inference complete! Processed {len(streaming_outputs_per_frame)} frames")
✓ Streaming inference complete! Processed 50 frames

# Access results
frame_0_outputs = streaming_outputs_per_frame[0]
print(f"Detected {len(frame_0_outputs['object_ids'])} objects in first frame")
print(f"Boxes are in XYXY format (absolute pixel coordinates): {frame_0_outputs['boxes'].shape}")
print(f"Masks are at original video resolution: {frame_0_outputs['masks'].shape}")
```

#### Inferensi Resolusi Kustom

⚠️ **Catatan Kinerja**: Resolusi kustom dapat menurunkan akurasi. Model ini dimaksudkan untuk digunakan pada resolusi 1008px.

Untuk inferensi yang lebih cepat atau penggunaan memori yang lebih rendah:

```python
config = Sam3VideoConfig.from_pretrained("facebook/sam3")
config.image_size = 560
model = Sam3VideoModel.from_pretrained("facebook/sam3", config=config, device_map="auto")
processor = Sam3VideoProcessor.from_pretrained("facebook/sam3", size={"height": 560, "width": 560})
```

## Sam3VideoConfig[[transformers.Sam3VideoConfig]]

#### transformers.Sam3VideoConfig[[transformers.Sam3VideoConfig]]

```python
transformers.Sam3VideoConfig(transformers_version: str | None = None, architectures: list[str] | None = None, output_hidden_states: bool | None = False, return_dict: bool | None = True, dtype: str | torch.dtype | None = None, chunk_size_feed_forward: int = 0, is_encoder_decoder: bool = False, id2label: dict[int, str] | dict[str, str] | None = None, label2id: dict[str, int] | dict[str, str] | None = None, problem_type: Literal['regression', 'single_label_classification', 'multi_label_classification'] | None = None, detector_config: dict | transformers.configuration_utils.PreTrainedConfig | None = None, tracker_config: dict | transformers.configuration_utils.PreTrainedConfig | None = None, initializer_range: float = 0.02, low_res_mask_size: int = 288, score_threshold_detection: float = 0.5, det_nms_thresh: float = 0.1, assoc_iou_thresh: float = 0.1, trk_assoc_iou_thresh: float = 0.5, new_det_thresh: float = 0.7, recondition_on_trk_masks: bool = True, hotstart_delay: int = 15, hotstart_unmatch_thresh: int = 8, hotstart_dup_thresh: int = 8, suppress_unmatched_only_within_hotstart: bool = True, init_trk_keep_alive: int = 30, max_trk_keep_alive: int = 30, min_trk_keep_alive: int = -1, suppress_overlapping_based_on_recent_occlusion_threshold: float = 0.7, decrease_trk_keep_alive_for_empty_masklets: bool = False, fill_hole_area: int = 16, max_num_objects: int = 10000, recondition_every_nth_frame: int = 16, high_conf_thresh: float = 0.8, high_iou_thresh: float = 0.8)
```

[Sumber](https://github.com/huggingface/transformers/blob/main/src/transformers/models/sam3_video/configuration_sam3_video.py#L28)

**Parameter:**

detector_config (`dict` atau `Sam3Config`, *opsional*) : Konfigurasi untuk model detektor Sam3. Jika tidak disediakan, Sam3Config default akan digunakan.

tracker_config (`dict` atau `Sam2VideoConfig`, *opsional*) : Konfigurasi untuk model pelacak Sam2Video. Jika tidak disediakan, Sam2VideoConfig default akan digunakan.

initializer_range (`float`, *opsional*, default 0.02) : Standar deviasi dari truncated_normal_initializer untuk menginisialisasi matriks bobot.

low_res_mask_size (`int`, *opsional*, defaultnya 288) : Ukuran (tinggi dan lebar) dari output mask resolusi rendah dari pelacak sebelum di-upsample ke resolusi video.

score_threshold_detection (`float`, *opsional*, default 0.5) : Ambang batas probabilitas untuk output deteksi - hanya simpan deteksi yang di atas ambang batas ini.

det_nms_thresh (`float`, *opsional*, default 0.1) : Ambang batas IoU untuk NMS (Non-Maximum Suppression) deteksi.

assoc_iou_thresh (`float`, *opsional*, default 0.1) : Ambang IoU untuk pencocokan deteksi ke track. Sebuah deteksi dianggap "cocok" dengan tracklet jika tumpang tindihnya dengan tracklet melebihi ambang ini. Biasanya menggunakan ambang yang longgar seperti 0.1.

trk_assoc_iou_thresh (`float`, *opsional*, default 0.5) : Ambang IoU untuk pencocokan deteksi-ke-track, digunakan untuk menentukan apakah sebuah masklet "tidak cocok" dengan deteksi mana pun. Sering kali digunakan ambang yang lebih ketat seperti 0.5.

new_det_thresh (`float`, *opsional*, default 0.7) : Ambang batas probabilitas agar deteksi ditambahkan sebagai objek baru.

recondition_on_trk_masks (`bool`, *opsional*, defaultnya `True`) : Apakah akan menggunakan masker yang dilacak (True) atau masker deteksi (False) untuk reconditioning. Gunakan True ketika masker yang dilacak memiliki kualitas lebih tinggi dan detektor berfungsi sebagai sinyal validasi untuk memperkuat memori dan mencegah drift.

hotstart_delay (`int`, *opsional*, default 15) : Jumlah frame untuk men-buffer output selama hotstart. Kami menahan output selama `hotstart_delay` frame dan menghapus tracklet berdasarkan heuristik hotstart.

hotstart_unmatch_thresh (`int`, *opsional*, default 8) : Jumlah frame yang tidak cocok yang diperlukan untuk menghapus tracklet selama periode hotstart.

hotstart_dup_thresh (`int`, *opsional*, default 8) : Jumlah frame tumpang tindih yang diperlukan untuk menghapus tracklet duplikat selama periode hotstart.

suppress_unmatched_only_within_hotstart (`bool`, *opsional*, defaultnya `True`) : Apakah akan menekan mask hanya di dalam periode hotstart. Jika False, kita dapat menekan mask meskipun dimulai sebelum periode hotstart.

init_trk_keep_alive (`int`, *opsional*, default 30) : Penghitung keep-alive awal untuk track baru.

max_trk_keep_alive (`int`, *opsional*, defaultnya 30) : Nilai maksimum penghitung keep-alive. Pelacakan dengan deteksi yang cocok akan memiliki penghitungnya ditingkatkan hingga nilai ini.

min_trk_keep_alive (`int`, *opsional*, defaultnya -1) : Nilai minimum penghitung keep-alive. Pelacak dengan deteksi yang tidak cocok akan memiliki penghitungnya dikurangi hingga nilai ini.

suppress_overlapping_based_on_recent_occlusion_threshold (`float`, *opsional*, default 0.7) : Ambang batas untuk menekan objek yang tumpang tindih berdasarkan oklusi terbaru. Mask yang tumpang tindih dengan IoU di atas ambang batas ini akan ditekan berdasarkan mana yang paling baru teroklusi.

decrease_trk_keep_alive_for_empty_masklets (`bool`, *opsional*, defaultnya `False`) : Apakah akan menurunkan penghitung keep-alive untuk masklet dengan area nol dalam prediksi SAM2.

fill_hole_area (`int`, *opsional*, default 16) : Luas minimum (dalam piksel) untuk mengisi lubang pada mask dan menghilangkan bintik-bintik kecil.

max_num_objects (`int`, *opsional*, default 10000) : Jumlah maksimum objek yang dilacak. Default 10000 secara efektif menonaktifkan batas ini.

recondition_every_nth_frame (`int`, *opsional*, default 16) : Frekuensi reconditioning mask (dalam frame). Setel ke 0 untuk menonaktifkan reconditioning.

high_conf_thresh (`float`, *opsional*, default 0.8) : Ambang batas kepercayaan tinggi untuk reconditioning. Hanya deteksi di atas ambang batas ini yang dapat melakukan reconditioning pada tracklet.

high_iou_thresh (`float`, *opsional*, default 0.8) : Ambang batas IoU tinggi untuk reconditioning. Hanya deteksi dengan IoU di atas ambang batas ini yang dapat melakukan reconditioning pada tracklet.

Ini adalah kelas konfigurasi untuk menyimpan konfigurasi dari Sam3VideoModel. Kelas ini digunakan untuk membuat instans model Sam3 Video sesuai dengan argumen yang ditentukan, yang mendefinisikan arsitektur model. Membuat instans konfigurasi dengan nilai bawaan akan menghasilkan konfigurasi yang serupa dengan konfigurasi dari [facebook/sam3](https://huggingface.co/facebook/sam3)

Objek konfigurasi mewarisi dari [PreTrainedConfig](/docs/transformers/main/id/main_classes/configuration#transformers.PreTrainedConfig) dan dapat digunakan untuk mengontrol keluaran model. Baca dokumentasi dari [PreTrainedConfig](/docs/transformers/main/id/main_classes/configuration#transformers.PreTrainedConfig) untuk informasi lebih lanjut.

Contoh:
```python
>>> from transformers import Sam3VideoConfig, Sam3VideoModel

>>> # Initializing a SAM3 Video configuration with default detector and tracker
>>> configuration = Sam3VideoConfig()

>>> # Changing image size for custom resolution inference (automatically propagates to all nested configs)
>>> configuration.image_size = 560

>>> # Initializing a model from the configuration
>>> model = Sam3VideoModel(configuration)

>>> # Accessing the model configuration
>>> configuration = model.config
>>> detector_config = configuration.detector_config
>>> tracker_config = configuration.tracker_config
```

## Sam3VideoProcessor[[transformers.Sam3VideoProcessor]]

#### transformers.Sam3VideoProcessor[[transformers.Sam3VideoProcessor]]

```python
transformers.Sam3VideoProcessor(image_processor, video_processor, tokenizer, target_size: int | None = None, **kwargs)
```

[Sumber](https://github.com/huggingface/transformers/blob/main/src/transformers/models/sam3_video/processing_sam3_video.py#L39)

**Parameter:**

image_processor (`Sam3ImageProcessor`) : Prosesor gambar adalah input yang wajib.

video_processor (`video_processor_class`) : Prosesor video adalah input yang wajib.

tokenizer (`CLIPTokenizer`) : Tokenizer adalah input yang wajib.

target_size (`int`, *opsional*) : Ukuran target (target_size, target_size) yang akan digunakan untuk mengubah ukuran gambar.

Membangun Sam3VideoProcessor yang membungkus image processor, video processor, dan tokenizer menjadi satu processor tunggal.

[Sam3VideoProcessor](/docs/transformers/main/id/model_doc/sam3_video#transformers.Sam3VideoProcessor) menyediakan semua fungsionalitas dari [Sam3ImageProcessor](/docs/transformers/main/id/model_doc/sam3#transformers.Sam3ImageProcessor), `video_processor_class`, dan [CLIPTokenizer](/docs/transformers/main/id/model_doc/clip#transformers.CLIPTokenizer). Lihat [~Sam3ImageProcessor](/docs/transformers/main/id/model_doc/sam3#transformers.Sam3ImageProcessor), `~video_processor_class`, dan [~CLIPTokenizer](/docs/transformers/main/id/model_doc/clip#transformers.CLIPTokenizer) untuk informasi lebih lanjut.

#### __call__[[transformers.Sam3VideoProcessor.__call__]]

```python
__call__(images: typing.Union[ForwardRef('PIL.Image.Image'), numpy.ndarray, ForwardRef('torch.Tensor'), list['PIL.Image.Image'], list[numpy.ndarray], list['torch.Tensor'], NoneType] = None, segmentation_maps: typing.Union[ForwardRef('PIL.Image.Image'), numpy.ndarray, ForwardRef('torch.Tensor'), list['PIL.Image.Image'], list[numpy.ndarray], list['torch.Tensor'], NoneType] = None, original_sizes: typing.Union[list[list[float]], torch.Tensor, NoneType] = None, return_tensors: str | transformers.utils.generic.TensorType | None = None, **kwargs)
```

[Sumber](https://github.com/huggingface/transformers/blob/main/src/transformers/models/sam3_video/processing_sam3_video.py#L55)

**Parameter:**

images (`ImageInput`, *opsional*) : Gambar yang akan diproses.

segmentation_maps (`ImageInput`, *opsional*) : Peta segmentasi yang akan diproses (opsional, untuk image processor).

original_sizes (`list[list[float]]`, `torch.Tensor`, *opsional*) : Ukuran asli dari gambar. Hanya digunakan ketika images tidak disediakan.

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:** Sebuah [BatchEncoding](/docs/transformers/main/id/main_classes/tokenizer#transformers.BatchEncoding) dengan field berikut

- `pixel_values` (`torch.Tensor`): Gambar yang telah diproses.
- `original_sizes` (`list[list[float]]`): Ukuran asli dari gambar-gambar tersebut.
- `labels` (`torch.Tensor`, *opsional*): Peta segmentasi yang telah diproses (jika disediakan).

#### postprocess_outputs[[transformers.Sam3VideoProcessor.postprocess_outputs]]

```python
postprocess_outputs(inference_session, model_outputs, original_sizes: typing.Union[list[list[float]], torch.Tensor, NoneType] = None)
```

[Sumber](https://github.com/huggingface/transformers/blob/main/src/transformers/models/sam3_video/processing_sam3_video.py#L247)

**Parameter:**

inference_session (`Sam3VideoInferenceSession`) : Objek sesi inferensi.

model_outputs (`Sam3VideoSegmentationOutput`) : Output mentah model dari `Sam3VideoModel.forward()`.

original_sizes (`list[list[float]]` atau `torch.Tensor`, *opsional*) : Ukuran frame asli opsional [tinggi, lebar]. Diperlukan untuk inferensi streaming ketika video_height/video_width tidak diatur dalam sesi.

**Mengembalikan:** `dict`

Kamus yang berisi kunci-kunci berikut:
- **object_ids** (`torch.Tensor` dengan bentuk `(num_objects,)`): ID objek untuk setiap objek yang terdeteksi.
- **scores** (`torch.Tensor` dengan bentuk `(num_objects,)`): Skor deteksi untuk setiap objek.
- **boxes** (`torch.Tensor` dengan bentuk `(num_objects, 4)`): Kotak pembatas dalam format XYXY (top_left_x, top_left_y, bottom_right_x, bottom_right_y).
- **masks** (`torch.Tensor` dengan bentuk `(num_objects, height, width)`): Mask segmentasi biner untuk setiap objek pada resolusi video asli.
- **prompt_to_obj_ids** (`dict[str, list[int]]`): Pemetaan dari teks prompt ke daftar ID objek yang terdeteksi oleh prompt tersebut.

Lakukan pascapemrosesan keluaran model untuk mendapatkan mask, kotak, dan skor akhir.

#### init_video_session[[transformers.Sam3VideoProcessor.init_video_session]]

```python
init_video_session(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] = None, inference_device: typing.Union[str, ForwardRef('torch.device')] = 'cpu', inference_state_device: typing.Union[str, ForwardRef('torch.device'), NoneType] = None, processing_device: typing.Union[str, ForwardRef('torch.device'), NoneType] = None, video_storage_device: typing.Union[str, ForwardRef('torch.device'), NoneType] = None, max_vision_features_cache_size: int = 1, dtype: dtype = torch.float32)
```

[Sumber](https://github.com/huggingface/transformers/blob/main/src/transformers/models/sam3_video/processing_sam3_video.py#L133)

**Parameter:**

video (`VideoInput`, *opsional*) : Video yang akan diproses. Tidak perlu disediakan saat streaming.

inference_device (`str` atau `torch.device`, *opsional*, defaultnya "cpu") : Perangkat yang akan digunakan untuk inferensi.

inference_state_device (`str` atau `torch.device`, *opsional*) : Perangkat untuk menyimpan state inferensi.

processing_device (`str` atau `torch.device`, *opsional*) : Perangkat yang akan digunakan untuk pemrosesan video.

video_storage_device (`str` atau `torch.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*, defaultnya `torch.float32`) : dtype torch yang akan digunakan untuk seluruh sesi.

Menginisialisasi sesi video untuk inferensi. Jika video disediakan (inferensi asinkron), video akan diproses dan disimpan di `video_storage_device`.

#### add_text_prompt[[transformers.Sam3VideoProcessor.add_text_prompt]]

```python
add_text_prompt(inference_session: Sam3VideoInferenceSession, text: str | list[str])
```

[Sumber](https://github.com/huggingface/transformers/blob/main/src/transformers/models/sam3_video/processing_sam3_video.py#L101)

**Parameter:**

inference_session (`Sam3VideoInferenceSession`) : Sesi inferensi.

text (`str` atau `list[str]`) : Prompt teks yang akan ditambahkan.

**Mengembalikan:** `Sam3VideoInferenceSession`

Sesi inferensi dengan prompt teks yang ditambahkan.

Tambahkan prompt teks ke sesi inferensi.

## Sam3VideoInferenceSession[[transformers.Sam3VideoInferenceSession]]

#### transformers.Sam3VideoInferenceSession[[transformers.Sam3VideoInferenceSession]]

```python
transformers.Sam3VideoInferenceSession(video: typing.Optional[torch.Tensor] = None, video_height: int | None = None, video_width: int | None = None, inference_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)
```

[Sumber](https://github.com/huggingface/transformers/blob/main/src/transformers/models/sam3_video/modeling_sam3_video.py#L119)

**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 akan digunakan untuk inferensi.

inference_state_device (`torch.device`, *opsional*, defaultnya `"cpu"`) : Perangkat untuk menyimpan state inferensi.

video_storage_device (`torch.device`, *opsional*, defaultnya `"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.

#### add_mask_inputs[[transformers.Sam3VideoInferenceSession.add_mask_inputs]]

```python
add_mask_inputs(obj_idx: int, frame_idx: int, inputs: Tensor)
```

[Sumber](https://github.com/huggingface/transformers/blob/main/src/transformers/models/sam3_video/modeling_sam3_video.py#L255)

Tambahkan input mask dengan penempatan perangkat otomatis.

#### add_new_frame[[transformers.Sam3VideoInferenceSession.add_new_frame]]

```python
add_new_frame(pixel_values: Tensor, frame_idx: int | None = None)
```

[Sumber](https://github.com/huggingface/transformers/blob/main/src/transformers/models/sam3_video/modeling_sam3_video.py#L384)

Tambahkan frame baru dengan penempatan perangkat otomatis.

#### add_prompt[[transformers.Sam3VideoInferenceSession.add_prompt]]

```python
add_prompt(prompt_text: str)
```

[Sumber](https://github.com/huggingface/transformers/blob/main/src/transformers/models/sam3_video/modeling_sam3_video.py#L215)

Tambahkan prompt teks ke sesi dan kembalikan ID uniknya. Jika prompt sudah ada, kembalikan ID yang sudah ada.

#### get_frame[[transformers.Sam3VideoInferenceSession.get_frame]]

```python
get_frame(frame_idx: int)
```

[Sumber](https://github.com/huggingface/transformers/blob/main/src/transformers/models/sam3_video/modeling_sam3_video.py#L400)

Ambil frame dari video.

#### get_obj_num[[transformers.Sam3VideoInferenceSession.get_obj_num]]

```python
get_obj_num()
```

[Sumber](https://github.com/huggingface/transformers/blob/main/src/transformers/models/sam3_video/modeling_sam3_video.py#L251)

Dapatkan jumlah total id objek unik yang diterima sejauh ini dalam sesi ini.

#### get_output[[transformers.Sam3VideoInferenceSession.get_output]]

```python
get_output(obj_idx: int, frame_idx: int, output_key: str, is_conditioning_frame: bool = True)
```

[Sumber](https://github.com/huggingface/transformers/blob/main/src/transformers/models/sam3_video/modeling_sam3_video.py#L357)

**Parameter:**

obj_idx (int) : Indeks dari objek.

frame_idx (int) : Indeks dari frame.

output_key (str) : Kunci dari output.

is_conditioning_frame (bool) : Apakah output tersebut untuk frame kondisioning.

Dapatkan output dengan manajemen perangkat pintar.

#### obj_id_to_idx[[transformers.Sam3VideoInferenceSession.obj_id_to_idx]]

```python
obj_id_to_idx(obj_id: int)
```

[Sumber](https://github.com/huggingface/transformers/blob/main/src/transformers/models/sam3_video/modeling_sam3_video.py#L229)

Petakan ID objek ke indeks, buat entri baru jika diperlukan.

#### obj_idx_to_id[[transformers.Sam3VideoInferenceSession.obj_idx_to_id]]

```python
obj_idx_to_id(obj_idx: int)
```

[Sumber](https://github.com/huggingface/transformers/blob/main/src/transformers/models/sam3_video/modeling_sam3_video.py#L247)

Petakan indeks objek sisi model ke id objek sisi klien.

#### remove_mask_inputs[[transformers.Sam3VideoInferenceSession.remove_mask_inputs]]

```python
remove_mask_inputs(obj_idx: int, frame_idx: int)
```

[Sumber](https://github.com/huggingface/transformers/blob/main/src/transformers/models/sam3_video/modeling_sam3_video.py#L261)

Hapus input mask.

#### remove_object[[transformers.Sam3VideoInferenceSession.remove_object]]

```python
remove_object(obj_id: int, strict: bool = False)
```

[Sumber](https://github.com/huggingface/transformers/blob/main/src/transformers/models/sam3_video/modeling_sam3_video.py#L265)

**Parameter:**

obj_id (`int`) : ID objek yang akan dihapus.

strict (`bool`, *opsional*, defaultnya `False`) : Apakah akan melempar error jika objek tidak ada.

Hapus objek dari sesi inferensi. Hal ini akan menghapus objek tersebut dari semua frame dalam video.

#### reset_inference_session[[transformers.Sam3VideoInferenceSession.reset_inference_session]]

```python
reset_inference_session()
```

[Sumber](https://github.com/huggingface/transformers/blob/main/src/transformers/models/sam3_video/modeling_sam3_video.py#L416)

Reset data pelacakan dan cache.

#### reset_state[[transformers.Sam3VideoInferenceSession.reset_state]]

```python
reset_state()
```

[Sumber](https://github.com/huggingface/transformers/blob/main/src/transformers/models/sam3_video/modeling_sam3_video.py#L428)

Reset status sesi inferensi.

#### reset_tracking_data[[transformers.Sam3VideoInferenceSession.reset_tracking_data]]

```python
reset_tracking_data()
```

[Sumber](https://github.com/huggingface/transformers/blob/main/src/transformers/models/sam3_video/modeling_sam3_video.py#L404)

Reset data pelacakan tetapi pertahankan cache.

#### store_output[[transformers.Sam3VideoInferenceSession.store_output]]

```python
store_output(obj_idx: int, frame_idx: int, output_key: str | None = None, output_value: typing.Union[torch.Tensor, dict, NoneType] = None, is_conditioning_frame: bool = True)
```

[Sumber](https://github.com/huggingface/transformers/blob/main/src/transformers/models/sam3_video/modeling_sam3_video.py#L320)

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

Simpan output dengan manajemen perangkat yang cerdas. Jika output_key adalah None, output disimpan sebagai kamus.

## Sam3VideoSegmentationOutput[[transformers.Sam3VideoSegmentationOutput]]

#### transformers.Sam3VideoSegmentationOutput[[transformers.Sam3VideoSegmentationOutput]]

```python
transformers.Sam3VideoSegmentationOutput(object_ids: list[int] | None = None, obj_id_to_mask: dict[int, torch.Tensor] | None = None, obj_id_to_score: dict[int, float] | None = None, obj_id_to_tracker_score: dict[int, float] | None = None, removed_obj_ids: set[int] | None = None, suppressed_obj_ids: set[int] | None = None, frame_idx: int | None = None)
```

[Sumber](https://github.com/huggingface/transformers/blob/main/src/transformers/models/sam3_video/modeling_sam3_video.py#L462)

**Parameter:**

object_ids (`list[int]`, *opsional*) : Daftar ID objek yang dilacak pada frame saat ini.

obj_id_to_mask (`dict[int, torch.Tensor]`, *opsional*) : Kamus yang memetakan ID objek ke mask resolusi rendah yang diprediksi. Setiap mask memiliki bentuk `(1, H_low, W_low)`.

obj_id_to_score (`dict[int, float]`, *opsional*) : Kamus yang memetakan ID objek ke skor deteksi mereka.

obj_id_to_tracker_score (`dict[int, float]`, *opsional*) : Kamus yang memetakan ID objek ke skor pelacaknya untuk frame saat ini.

removed_obj_ids (`set[int]`, *opsional*) : Himpunan ID objek yang telah dihapus (misalnya, melalui heuristik hotstart).

suppressed_obj_ids (`set[int]`, *opsional*) : Himpunan ID objek yang telah diredam di frame saat ini.

frame_idx (`int`, *opsional*) : Indeks frame dari video.

Kelas dasar untuk output model Sam3Video.

## Sam3VideoModel[[transformers.Sam3VideoModel]]

#### transformers.Sam3VideoModel[[transformers.Sam3VideoModel]]

```python
transformers.Sam3VideoModel(config: Sam3VideoConfig)
```

[Sumber](https://github.com/huggingface/transformers/blob/main/src/transformers/models/sam3_video/modeling_sam3_video.py#L507)

**Parameter:**

config ([Sam3VideoConfig](/docs/transformers/main/id/model_doc/sam3_video#transformers.Sam3VideoConfig)) : Kelas konfigurasi model dengan semua parameter model. Inisialisasi dengan file konfigurasi tidak memuat bobot yang terkait dengan model, hanya konfigurasinya. Lihat metode [from_pretrained()](/docs/transformers/main/id/main_classes/model#transformers.PreTrainedModel.from_pretrained) untuk memuat bobot model.

Model Sam3 Video polos yang menghasilkan hidden-states mentah tanpa head spesifik di atasnya.

Model ini mewarisi dari [PreTrainedModel](/docs/transformers/main/id/main_classes/model#transformers.PreTrainedModel). Periksa dokumentasi kelas induk untuk metode generik yang diimplementasikan oleh pustaka ini untuk semua model (seperti mengunduh atau menyimpan, mengubah ukuran input embeddings, memangkas heads, dll.)

Model ini juga merupakan subclass dari [torch.nn.Module](https://pytorch.org/docs/stable/nn.html#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[[transformers.Sam3VideoModel.forward]]

```python
forward(inference_session: Sam3VideoInferenceSession, frame_idx: int | None = None, frame: typing.Optional[torch.Tensor] = None, reverse: bool = False, **kwargs)
```

[Sumber](https://github.com/huggingface/transformers/blob/main/src/transformers/models/sam3_video/modeling_sam3_video.py#L1693)

**Parameter:**

inference_session (`~models.sam3_video.modeling_sam3_video.Sam3VideoInferenceSession`) : Objek sesi inferensi video.

frame_idx (`int`, *opsional*) : Indeks dari 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*, defaultnya `False`) : Apakah akan melakukan propagasi secara terbalik.

Propagasi objek melalui bingkai video yang dialirkan.

#### propagate_in_video_iterator[[transformers.Sam3VideoModel.propagate_in_video_iterator]]

```python
propagate_in_video_iterator(inference_session: Sam3VideoInferenceSession, start_frame_idx: int = 0, max_frame_num_to_track: int | None = None, reverse: bool = False, show_progress_bar: bool = False)
```

[Sumber](https://github.com/huggingface/transformers/blob/main/src/transformers/models/sam3_video/modeling_sam3_video.py#L1784)

**Parameter:**

inference_session (`~models.sam3_video.modeling_sam3_video.Sam3VideoInferenceSession`) : Objek sesi inferensi video.

start_frame_idx (`int`, *opsional*, defaultnya `0`) : Indeks frame awal untuk propagasi.

max_frame_num_to_track (`int`, *opsional*) : Jumlah maksimum frame yang akan dilacak. Jika tidak diberikan, semua frame dalam video akan dilacak.

reverse (`bool`, *opsional*, defaultnya `False`) : Apakah akan melakukan propagasi secara terbalik.

show_progress_bar (`bool`, *opsional*, defaultnya `False`) : Apakah akan menampilkan bilah kemajuan selama propagasi.

**Mengembalikan:** [Sam3VideoSegmentationOutput](/docs/transformers/main/id/model_doc/sam3_video#transformers.Sam3VideoSegmentationOutput) atau `tuple(torch.Tensor)`

Sebuah [Sam3VideoSegmentationOutput](/docs/transformers/main/id/model_doc/sam3_video#transformers.Sam3VideoSegmentationOutput) atau tuple dari `torch.Tensor` (jika `return_dict=False` diteruskan atau ketika `config.return_dict=False`) yang terdiri dari berbagai elemen tergantung pada konfigurasi ([Sam3VideoConfig](/docs/transformers/main/id/model_doc/sam3_video#transformers.Sam3VideoConfig)) dan input.

Propagasi prompt untuk mendapatkan hasil grounding untuk seluruh video. Digunakan saat menginisialisasi sesi inferensi dengan video utuh. Menghasilkan Sam3VideoSegmentationOutput untuk setiap frame.

- **object_ids** (`list[int]`, *opsional*) -- Daftar ID objek yang dilacak pada frame saat ini.
- **obj_id_to_mask** (`dict[int, torch.Tensor]`, *opsional*) -- Kamus yang memetakan ID objek ke mask resolusi rendah yang diprediksi. Setiap mask memiliki bentuk `(1, H_low, W_low)`.
- **obj_id_to_score** (`dict[int, float]`, *opsional*) -- Kamus yang memetakan ID objek ke skor deteksinya.
- **obj_id_to_tracker_score** (`dict[int, float]`, *opsional*) -- Kamus yang memetakan ID objek ke skor pelacaknya untuk frame saat ini.
- **removed_obj_ids** (`set[int]`, *opsional*) -- Himpunan ID objek yang telah dihapus (misalnya, melalui heuristik hotstart).
- **suppressed_obj_ids** (`set[int]`, *opsional*) -- Himpunan ID objek yang telah diredam di frame saat ini.
- **frame_idx** (`int`, *opsional*) -- Indeks frame dari video.