# SAM3 Tracker

    
        
        
    

## Tổng quan

SAM3 (Segment Anything Model 3) được giới thiệu trong [SAM 3: Segment Anything with Concepts](https://ai.meta.com/research/publications/sam-3-segment-anything-with-concepts/).

Sam3Tracker thực hiện **Phân đoạn thị giác có thể gợi ý (Promptable Visual Segmentation - PVS)** trên các hình ảnh. PVS nhận các gợi ý thị giác tương tác (điểm, hộp, mặt nạ) hoặc đầu vào dạng văn bản để phân đoạn một **thực thể đối tượng cụ thể** cho mỗi gợi ý. Đây là nhiệm vụ mà SAM 1 và SAM 2 tập trung vào, và SAM 3 đã cải thiện nó.

Sam3Tracker là phiên bản cập nhật của SAM2 (Segment Anything Model 2), giữ nguyên API nhưng cung cấp hiệu suất và khả năng được cải thiện.

Tóm tắt từ bài báo như sau:

*Chúng tôi giới thiệu Segment Anything Model (SAM) 3, một mô hình thống nhất có khả năng phát hiện, phân đoạn và theo dõi các đối tượng trong ảnh và video dựa trên các prompt khái niệm, được chúng tôi định nghĩa là các cụm danh từ ngắn (ví dụ: "yellow school bus"), các ví dụ hình ảnh, hoặc sự kết hợp của cả hai. Promptable Concept Segmentation (PCS) nhận các prompt như vậy và trả về các mặt nạ phân đoạn cùng với danh tính duy nhất cho tất cả các phiên bản đối tượng khớp. Để thúc đẩy PCS, chúng tôi xây dựng một động cơ dữ liệu có khả năng mở rộng, tạo ra một bộ dữ liệu chất lượng cao với 4 triệu nhãn khái niệm duy nhất, bao gồm cả các âm tính khó, trên cả ảnh và video. Mô hình của chúng tôi bao gồm một bộ phát hiện ở cấp độ ảnh và một bộ theo dõi video dựa trên bộ nhớ, chia sẻ một backbone duy nhất. Nhận dạng và định vị được tách rời bằng một presence head, giúp tăng độ chính xác của việc phát hiện. SAM 3 gấp đôi độ chính xác so với các hệ thống hiện có trong cả PCS trên ảnh và video, đồng thời cải thiện các khả năng trước đó của SAM trên các nhiệm vụ phân đoạn thị giác. Chúng tôi mã nguồn mở SAM 3 cùng với bộ chuẩn đánh giá mới Segment Anything with Concepts (SA-Co) của chúng tôi cho phân đoạn khái niệm có thể prompt.*

Mô hình này được đóng góp bởi [yonigozlan](https://huggingface.co/yonigozlan) và [ronghanghu](https://huggingface.co/ronghanghu).

## Ví dụ sử dụng

### Tự động tạo mặt nạ với Pipeline

Sam3Tracker có thể được sử dụng để tạo mask tự động nhằm phân đoạn tất cả các đối tượng trong một hình ảnh bằng cách sử dụng pipeline `mask-generation`:

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

### Phân đoạn hình ảnh cơ bản

#### Nhấp một điểm

Bạn có thể phân đoạn các đối tượng bằng cách nhấp một điểm duy nhất vào đối tượng mà bạn muốn phân đoạn:

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

#### Nhiều điểm để tinh chỉnh

Bạn có thể cung cấp nhiều điểm để tinh chỉnh phân đoạn:

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

#### Đầu vào Hộp Chứa

Sam3Tracker cũng hỗ trợ đầu vào hộp bao quanh (bounding box) cho phân đoạn:

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

#### Phân đoạn nhiều đối tượng

Bạn có thể phân đoạn nhiều đối tượng đồng thời:

```python
# 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
```

### Suy luận theo lô

#### Hình ảnh theo lô

Xử lý nhiều hình ảnh đồng thời để cải thiện hiệu suất:

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

#### Các Đối tượng được Xử lý theo Lô cho Mỗi Ảnh

Phân đoạn nhiều đối tượng trong mỗi hình ảnh bằng suy luận theo lô:

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

#### Hình ảnh theo lô với các đối tượng theo lô và nhiều điểm

Xử lý các kịch bản batch phức tạp với nhiều điểm cho mỗi đối tượng:

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

#### Hộp bao dạng lô

Xử lý nhiều hình ảnh với đầu vào là hộp bao quanh:

```python
# 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
```

### Sử dụng Mặt nạ Trước đó làm Đầu vào

Sam3Tracker có thể sử dụng các mask từ các dự đoán trước đó làm đầu vào để tinh chỉnh phân đoạn:

```python
# Get initial segmentation
input_points = [[[[500, 375]]]]
input_labels = [[[1]]]
inputs = processor(images=raw_image, input_points=input_points, input_labels=input_labels, return_tensors="pt").to(model.device)

with torch.no_grad():
    outputs = model(**inputs)

# Use the best mask as input for refinement
mask_input = outputs.pred_masks[:, :, torch.argmax(outputs.iou_scores.squeeze())]

# Add additional points with the mask input
new_input_points = [[[[500, 375], [450, 300]]]]
new_input_labels = [[[1, 1]]]
inputs = processor(
    input_points=new_input_points,
    input_labels=new_input_labels,
    original_sizes=inputs["original_sizes"],
    return_tensors="pt",
).to(model.device)

with torch.no_grad():
    refined_outputs = model(
        **inputs,
        input_masks=mask_input,
        image_embeddings=outputs.image_embeddings,
        multimask_output=False,
    )
```

## Sam3TrackerConfig[[transformers.Sam3TrackerConfig]]

#### transformers.Sam3TrackerConfig[[transformers.Sam3TrackerConfig]]

```python
transformers.Sam3TrackerConfig(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, vision_config: dict | transformers.configuration_utils.PreTrainedConfig | None = None, prompt_encoder_config: dict | transformers.configuration_utils.PreTrainedConfig | None = None, mask_decoder_config: dict | transformers.configuration_utils.PreTrainedConfig | None = None, initializer_range: float = 0.02)
```

[Nguồn](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/sam3_tracker/configuration_sam3_tracker.py#L96)

**Tham số:**

vision_config (`Union[dict, ~configuration_utils.PreTrainedConfig]`, *tùy chọn*) : Đối tượng config hoặc từ điển của vision backbone.

prompt_encoder_config (Union[`dict`, `Sam3TrackerPromptEncoderConfig`], *optional*) : Từ điển các tùy chọn cấu hình được sử dụng để khởi tạo [Sam3TrackerPromptEncoderConfig](/docs/transformers/v5.23.0/vi/model_doc/sam3_tracker#transformers.Sam3TrackerPromptEncoderConfig).

mask_decoder_config (Union[`dict`, `Sam3TrackerMaskDecoderConfig`], *optional*) : Từ điển các tùy chọn cấu hình được sử dụng để khởi tạo [Sam3TrackerMaskDecoderConfig](/docs/transformers/v5.23.0/vi/model_doc/sam3_tracker#transformers.Sam3TrackerMaskDecoderConfig).

initializer_range (`float`, *optional*, mặc định là `0.02`) : Độ lệch chuẩn của truncated_normal_initializer để khởi tạo tất cả các ma trận trọng số.

Đây là lớp cấu hình để lưu trữ cấu hình của một Sam3TrackerModel. Nó được sử dụng để khởi tạo một mô hình Sam3 Tracker theo các đối số được chỉ định, xác định kiến trúc mô hình. Khởi tạo một cấu hình với các giá trị mặc định sẽ tạo ra một cấu hình tương tự như của [facebook/sam3](https://huggingface.co/facebook/sam3)

Các đối tượng cấu hình kế thừa từ [PreTrainedConfig](/docs/transformers/v5.23.0/vi/main_classes/configuration#transformers.PreTrainedConfig) và có thể được sử dụng để kiểm soát đầu ra của mô hình. Đọc tài liệu từ [PreTrainedConfig](/docs/transformers/v5.23.0/vi/main_classes/configuration#transformers.PreTrainedConfig) để biết thêm thông tin.

Ví dụ:

```python
>>> from transformers import (
...     Sam3TrackerVisionConfig,
...     Sam3TrackerPromptEncoderConfig,
...     Sam3TrackerMaskDecoderConfig,
...     Sam3TrackerModel,
... )

>>> # Initializing a Sam3TrackerConfig with `"facebook/sam3_tracker.1_hiera_tiny"` style configuration
>>> configuration = Sam3TrackerConfig()

>>> # Initializing a Sam3TrackerModel (with random weights) from the `"facebook/sam3_tracker.1_hiera_tiny"` style configuration
>>> model = Sam3TrackerModel(configuration)

>>> # Accessing the model configuration
>>> configuration = model.config

>>> # We can also initialize a Sam3TrackerConfig from a Sam3TrackerVisionConfig, Sam3TrackerPromptEncoderConfig, and Sam3TrackerMaskDecoderConfig
>>> # Initializing SAM3_TRACKER vision encoder, memory attention, and memory encoder configurations
>>> vision_config = Sam3TrackerVisionConfig()
>>> prompt_encoder_config = Sam3TrackerPromptEncoderConfig()
>>> mask_decoder_config = Sam3TrackerMaskDecoderConfig()

>>> config = Sam3TrackerConfig(vision_config, prompt_encoder_config, mask_decoder_config)
```

## Sam3TrackerPromptEncoderConfig[[transformers.Sam3TrackerPromptEncoderConfig]]

#### transformers.Sam3TrackerPromptEncoderConfig[[transformers.Sam3TrackerPromptEncoderConfig]]

```python
transformers.Sam3TrackerPromptEncoderConfig(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, hidden_size: int = 256, image_size: int | list[int] | tuple[int, int] = 1008, patch_size: int | list[int] | tuple[int, int] = 14, mask_input_channels: int = 16, num_point_embeddings: int = 4, hidden_act: str = 'gelu', layer_norm_eps: float = 1e-06, scale: int = 1)
```

[Nguồn](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/sam3_tracker/configuration_sam3_tracker.py#L31)

**Tham số:**

hidden_size (`int`, *tuỳ chọn*, mặc định là `256`) : Kích thước của các biểu diễn ẩn.

image_size (`Union[int, list[int], tuple[int, int]]`, *tùy chọn*, mặc định là `1008`) : Kích thước (độ phân giải) của mỗi hình ảnh.

patch_size (`Union[int, list[int], tuple[int, int]]`, *tùy chọn*, mặc định là `14`) : Kích thước (độ phân giải) của mỗi patch.

mask_input_channels (`int`, *tuỳ chọn*, mặc định là 16) : Số lượng kênh được đưa vào module `MaskDecoder`.

num_point_embeddings (`int`, *tuỳ chọn*, mặc định là 4) : Số lượng point embeddings sẽ được sử dụng.

hidden_act (`str`, *tùy chọn*, mặc định là `gelu`) : Hàm kích hoạt phi tuyến (hàm hoặc chuỗi) trong bộ giải mã. Ví dụ, `"gelu"`, `"relu"`, `"silu"`, v.v.

layer_norm_eps (`float`, *tuỳ chọn*, mặc định là `1e-06`) : Epsilon được sử dụng bởi các lớp chuẩn hóa lớp (layer normalization).

scale (`float`, *tuỳ chọn*, mặc định là 1) : Hệ số tỷ lệ cho bộ mã hóa prompt.

Đây là lớp cấu hình để lưu trữ cấu hình của một Sam3TrackerModel. Nó được sử dụng để khởi tạo một mô hình Sam3 Tracker theo các đối số được chỉ định, xác định kiến trúc mô hình. Khởi tạo một cấu hình với các giá trị mặc định sẽ tạo ra một cấu hình tương tự như của [facebook/sam3](https://huggingface.co/facebook/sam3)

Các đối tượng cấu hình kế thừa từ [PreTrainedConfig](/docs/transformers/v5.23.0/vi/main_classes/configuration#transformers.PreTrainedConfig) và có thể được sử dụng để kiểm soát đầu ra của mô hình. Đọc tài liệu từ [PreTrainedConfig](/docs/transformers/v5.23.0/vi/main_classes/configuration#transformers.PreTrainedConfig) để biết thêm thông tin.

## Sam3TrackerMaskDecoderConfig[[transformers.Sam3TrackerMaskDecoderConfig]]

#### transformers.Sam3TrackerMaskDecoderConfig[[transformers.Sam3TrackerMaskDecoderConfig]]

```python
transformers.Sam3TrackerMaskDecoderConfig(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, hidden_size: int = 256, hidden_act: str = 'gelu', mlp_dim: int = 2048, num_hidden_layers: int = 2, num_attention_heads: int = 8, attention_downsample_rate: int = 2, num_multimask_outputs: int = 3, iou_head_depth: int = 3, iou_head_hidden_dim: int = 256, dynamic_multimask_via_stability: bool = True, dynamic_multimask_stability_delta: float = 0.05, dynamic_multimask_stability_thresh: float = 0.98)
```

[Nguồn](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/sam3_tracker/configuration_sam3_tracker.py#L57)

**Tham số:**

hidden_size (`int`, *tuỳ chọn*, mặc định là `256`) : Kích thước của các biểu diễn ẩn.

hidden_act (`str`, *tùy chọn*, mặc định là `gelu`) : Hàm kích hoạt phi tuyến (hàm hoặc chuỗi) trong bộ giải mã. Ví dụ, `"gelu"`, `"relu"`, `"silu"`, v.v.

mlp_dim (`int`, *tuỳ chọn*, mặc định là 2048) : Kích thước của MLP trong transformer hai chiều.

num_hidden_layers (`int`, *tuỳ chọn*, mặc định là `2`) : Số lượng lớp ẩn trong bộ giải mã Transformer.

num_attention_heads (`int`, *tuỳ chọn*, mặc định là `8`) : Số lượng đầu chú ý cho mỗi lớp chú ý trong bộ giải mã Transformer.

attention_downsample_rate (`int`, *tuỳ chọn*, mặc định là 2) : Tốc độ hạ mẫu cho các lớp attention.

num_multimask_outputs (`int`, *tuỳ chọn*, mặc định là 3) : Số lượng đầu ra multimask.

iou_head_depth (`int`, *tuỳ chọn*, mặc định là 3) : Độ sâu của đầu IoU.

iou_head_hidden_dim (`int`, *optional*, mặc định là 256) : Kích thước chiều ẩn của đầu IoU.

dynamic_multimask_via_stability (`bool`, *tùy chọn*, mặc định là `True`) : Có sử dụng dynamic multimask thông qua stability hay không.

dynamic_multimask_stability_delta (`float`, *tuỳ chọn*, mặc định là 0.05) : Độ lệch ổn định cho dynamic multimask.

dynamic_multimask_stability_thresh (`float`, *optional*, mặc định là 0.98) : Ngưỡng ổn định cho dynamic multimask.

Đây là lớp cấu hình để lưu trữ cấu hình của một Sam3TrackerModel. Nó được sử dụng để khởi tạo một mô hình Sam3 Tracker theo các đối số được chỉ định, xác định kiến trúc mô hình. Khởi tạo một cấu hình với các giá trị mặc định sẽ tạo ra một cấu hình tương tự như của [facebook/sam3](https://huggingface.co/facebook/sam3)

Các đối tượng cấu hình kế thừa từ [PreTrainedConfig](/docs/transformers/v5.23.0/vi/main_classes/configuration#transformers.PreTrainedConfig) và có thể được sử dụng để kiểm soát đầu ra của mô hình. Đọc tài liệu từ [PreTrainedConfig](/docs/transformers/v5.23.0/vi/main_classes/configuration#transformers.PreTrainedConfig) để biết thêm thông tin.

## Sam3TrackerProcessor[[transformers.Sam3TrackerProcessor]]

#### transformers.Sam3TrackerProcessor[[transformers.Sam3TrackerProcessor]]

```python
transformers.Sam3TrackerProcessor(image_processor, target_size: int | None = None, point_pad_value: int = -10, **kwargs)
```

[Nguồn](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/sam3_tracker/processing_sam3_tracker.py#L36)

**Tham số:**

image_processor (`Sam3ImageProcessor`) : Bộ xử lý ảnh là một đầu vào bắt buộc.

target_size (`int`, *optional*) : Kích thước đích (tính bằng pixel) để chuẩn hóa các điểm đầu vào và hộp bao. Nếu không được cung cấp, mặc định sẽ dùng cấu hình kích thước của bộ xử lý ảnh. Tất cả các tọa độ đầu vào (điểm và hộp) sẽ được chuẩn hóa theo kích thước này trước khi được truyền vào mô hình. Điều này đảm bảo biểu diễn tọa độ nhất quán bất kể kích thước gốc của ảnh.

point_pad_value (`int`, *optional*, mặc định là -10) : Giá trị được dùng để đệm (padding) các điểm đầu vào khi xử lý các chuỗi có độ dài khác nhau theo lô (batching). Giá trị này được dùng để đánh dấu các vị trí đã đệm và được giữ nguyên trong quá trình chuẩn hóa tọa độ.

Tạo một Sam3TrackerProcessor, đóng gói một bộ xử lý ảnh thành một bộ xử lý duy nhất.

[Sam3TrackerProcessor](/docs/transformers/v5.23.0/vi/model_doc/sam3_tracker#transformers.Sam3TrackerProcessor) cung cấp đầy đủ các chức năng của [Sam3ImageProcessor](/docs/transformers/v5.23.0/vi/model_doc/sam3#transformers.Sam3ImageProcessor). Xem [~Sam3ImageProcessor](/docs/transformers/v5.23.0/vi/model_doc/sam3#transformers.Sam3ImageProcessor) để biết thêm thông tin.

#### __call__[[transformers.Sam3TrackerProcessor.__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, input_points: typing.Union[list[list[list[list[float]]]], torch.Tensor, NoneType] = None, input_labels: typing.Union[list[list[list[int]]], torch.Tensor, NoneType] = None, input_boxes: typing.Union[list[list[list[float]]], 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)
```

[Nguồn](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/sam3_tracker/processing_sam3_tracker.py#L52)

**Tham số:**

images (`Union[PIL.Image.Image, numpy.ndarray, torch.Tensor, list[PIL.Image.Image], list[numpy.ndarray], list[torch.Tensor]]`, *tùy chọn*) : Ảnh cần tiền xử lý. Kỳ vọng một ảnh đơn hoặc một lô ảnh với giá trị pixel dao động từ 0 đến 255. Nếu truyền vào các ảnh có giá trị pixel nằm trong khoảng từ 0 đến 1, hãy đặt `do_rescale=False`.

segmentation_maps (`ImageInput`, *tùy chọn*) : Các bản đồ phân đoạn cần xử lý.

input_points (`list[list[list[list[float]]]]`, `torch.Tensor`, *tùy chọn*) : Các điểm cần thêm vào khung.

input_labels (`list[list[list[int]]]`, `torch.Tensor`, *tùy chọn*) : Nhãn cho các điểm.

input_boxes (`list[list[list[float]]]`, `torch.Tensor`, *tùy chọn*) : Các hộp bao (bounding boxes) cần thêm vào khung hình.

original_sizes (`list[list[float]]`, `torch.Tensor`, *tùy chọn*) : Kích thước gốc của các hình ảnh.

return_tensors (`Union[str, ~utils.generic.TensorType]`, *tùy chọn*) : Nếu được đặt, sẽ trả về các tensor của một framework cụ thể. Các giá trị chấp nhận được là:  - `'pt'`: Trả về các đối tượng `torch.Tensor` của PyTorch. - `'np'`: Trả về các đối tượng `np.ndarray` của NumPy.

**Trả về:** Một [BatchEncoding](/docs/transformers/v5.23.0/vi/main_classes/tokenizer#transformers.BatchEncoding) với các trường sau

- `pixel_values` (`torch.Tensor`): Ảnh đã được xử lý.
- `original_sizes` (`list[list[float]]`): Kích thước gốc của các hình ảnh.
- `labels` (`torch.Tensor`): Các bản đồ phân đoạn đã được xử lý (nếu được cung cấp).
- `input_points` (`torch.Tensor`): Các điểm đã được xử lý.
- `input_labels` (`torch.Tensor`): Nhãn đã được xử lý.
- `input_boxes` (`torch.Tensor`): Các hộp bao đã được xử lý.

#### post_process_masks[[transformers.Sam3TrackerProcessor.post_process_masks]]

```python
post_process_masks(masks, original_sizes, mask_threshold = 0.0, binarize = True, max_hole_area = 0.0, max_sprinkle_area = 0.0, apply_non_overlapping_constraints = False, **kwargs)
```

[Nguồn](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/sam3_tracker/processing_sam3_tracker.py#L458)

**Tham số:**

masks (`Union[List[torch.Tensor], List[np.ndarray]]`) : Các mask dạng batch từ mask_decoder ở định dạng (batch_size, num_channels, height, width).

original_sizes (`Union[torch.Tensor, List[Tuple[int,int]]]`) : Kích thước gốc của từng ảnh trước khi được điều chỉnh kích thước thành hình dạng đầu vào mong đợi của mô hình, theo định dạng (chiều cao, chiều rộng).

mask_threshold (`float`, *tuỳ chọn*, mặc định là 0.0) : Ngưỡng cho các thao tác nhị phân hóa và xử lý hậu kỳ.

binarize (`bool`, *tùy chọn*, mặc định là `True`) : Xác định có nhị phân hóa các mặt nạ hay không.

max_hole_area (`float`, *tuỳ chọn*, mặc định là 0.0) : Diện tích tối đa của một lỗ cần lấp đầy.

max_sprinkle_area (`float`, *tuỳ chọn*, mặc định là 0.0) : Diện tích tối đa của một vệt rắc để lấp đầy.

apply_non_overlapping_constraints (`bool`, *tùy chọn*, mặc định là `False`) : Có áp dụng các ràng buộc không chồng chéo lên các mặt nạ hay không.

**Trả về:** (`torch.Tensor`)

Mặt nạ dạng batch có định dạng batch_size, num_channels, height, width, trong đó (height, width) được xác định bởi original_size.

Loại bỏ padding và phóng to các mask lên kích thước ảnh gốc.

## Sam3TrackerModel[[transformers.Sam3TrackerModel]]

#### transformers.Sam3TrackerModel[[transformers.Sam3TrackerModel]]

```python
transformers.Sam3TrackerModel(config: Sam3TrackerConfig)
```

[Nguồn](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/sam3_tracker/modeling_sam3_tracker.py#L772)

**Tham số:**

config ([Sam3TrackerConfig](/docs/transformers/v5.23.0/vi/model_doc/sam3_tracker#transformers.Sam3TrackerConfig)) : Lớp cấu hình mô hình chứa tất cả các tham số của mô hình. Khởi tạo bằng tệp cấu hình sẽ không tải trọng số liên quan đến mô hình, chỉ tải cấu hình. Xem phương thức [from_pretrained()](/docs/transformers/v5.23.0/vi/main_classes/model#transformers.PreTrainedModel.from_pretrained) để tải trọng số mô hình.

Mô hình Segment Anything 2 (SAM 2) để tạo các mặt nạ phân đoạn, dựa trên ảnh đầu vào cùng các điểm và nhãn đầu vào, hộp hoặc mặt nạ.

Mô hình này kế thừa từ [PreTrainedModel](/docs/transformers/v5.23.0/vi/main_classes/model#transformers.PreTrainedModel). Xem tài liệu của lớp cha để biết các phương thức chung mà thư viện triển khai cho tất cả các mô hình của nó (chẳng hạn như tải xuống hoặc lưu trữ, thay đổi kích thước các nhúng đầu vào, cắt tỉa các đầu ra, v.v.)

Mô hình này cũng là một lớp con của [torch.nn.Module](https://pytorch.org/docs/stable/nn.html#torch.nn.Module) trong PyTorch. Hãy sử dụng nó như một Module PyTorch thông thường và tham khảo tài liệu PyTorch cho mọi vấn đề liên quan đến cách sử dụng và hành vi chung.

#### forward[[transformers.Sam3TrackerModel.forward]]

```python
forward(pixel_values: typing.Optional[torch.Tensor] = None, input_points: typing.Optional[torch.Tensor] = None, input_labels: typing.Optional[torch.LongTensor] = None, input_boxes: typing.Optional[torch.Tensor] = None, input_masks: typing.Optional[torch.LongTensor] = None, image_embeddings: typing.Optional[torch.Tensor] = None, multimask_output: bool = True, attention_similarity: typing.Optional[torch.Tensor] = None, target_embedding: typing.Optional[torch.Tensor] = None, **kwargs: *<class 'transformers.utils.generic.TransformersKwargs'>)
```

[Nguồn](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/sam3_tracker/modeling_sam3_tracker.py#L886)

**Tham số:**

pixel_values (`torch.Tensor` có hình dạng `(batch_size, num_channels, image_size, image_size)`, *tùy chọn*) : Các tensor tương ứng với các hình ảnh đầu vào. Giá trị pixel có thể được lấy bằng cách sử dụng [Sam3ImageProcessor](/docs/transformers/v5.23.0/vi/model_doc/sam3#transformers.Sam3ImageProcessor). Xem [Sam3ImageProcessor.__call__()](/docs/transformers/v5.23.0/vi/model_doc/molmo2#transformers.Molmo2ImageProcessor.__call__) để biết chi tiết ([Sam3TrackerProcessor](/docs/transformers/v5.23.0/vi/model_doc/sam3_tracker#transformers.Sam3TrackerProcessor) sử dụng [Sam3ImageProcessor](/docs/transformers/v5.23.0/vi/model_doc/sam3#transformers.Sam3ImageProcessor) để xử lý hình ảnh).

input_points (`torch.Tensor` có shape `(batch_size, num_points, 2)`) : Các điểm không gian 2D đầu vào, được prompt encoder sử dụng để mã hóa prompt. Thông thường cho kết quả tốt hơn đáng kể. Các điểm này có thể được tạo ra bằng cách truyền một danh sách các danh sách con vào processor, processor sẽ tạo ra các tensor `torch` tương ứng có 4 chiều. Chiều đầu tiên là kích thước batch của ảnh, chiều thứ hai là kích thước batch của điểm (tức là số lượng mask phân đoạn mà chúng ta muốn mô hình dự đoán cho mỗi điểm đầu vào), chiều thứ ba là số điểm cho mỗi mask phân đoạn (có thể truyền nhiều điểm cho một mask duy nhất), và chiều cuối cùng là tọa độ x (dọc) và y (ngang) của điểm. Nếu số lượng điểm được truyền khác nhau cho mỗi ảnh, hoặc cho mỗi mask, processor sẽ tạo ra các điểm "PAD" tương ứng với tọa độ (0, 0), và việc tính toán embedding sẽ bị bỏ qua cho các điểm này bằng cách sử dụng labels.

input_labels (`torch.LongTensor` có shape `(batch_size, point_batch_size, num_points)`) : Nhãn đầu vào cho các điểm, được prompt encoder sử dụng để mã hóa prompt. Theo cài đặt chính thức, có 3 loại nhãn - `1`: điểm chứa đối tượng quan tâm - `0`: điểm không chứa đối tượng quan tâm - `-1`: điểm tương ứng với nền  Chúng tôi đã thêm nhãn: - `-10`: điểm là điểm đệm, do đó nên được prompt encoder bỏ qua  Việc gán nhãn đệm nên được thực hiện tự động bởi processor.

input_boxes (`torch.Tensor` có shape `(batch_size, num_boxes, 4)`) : Các hộp đầu vào cho các điểm, được prompt encoder sử dụng để mã hóa prompt. Nhìn chung, cách này tạo ra các mask tốt hơn đáng kể. Các hộp có thể được lấy bằng cách truyền một danh sách các danh sách con vào processor, từ đó tạo ra một tensor `torch`, trong đó mỗi chiều lần lượt tương ứng với kích thước batch của ảnh, số lượng hộp trên mỗi ảnh và tọa độ của điểm góc trên bên trái và điểm góc dưới bên phải của hộp. Theo thứ tự (`x1`, `y1`, `x2`, `y2`):  - `x1`: tọa độ x của điểm góc trên bên trái của hộp đầu vào - `y1`: tọa độ y của điểm góc trên bên trái của hộp đầu vào - `x2`: tọa độ x của điểm góc dưới bên phải của hộp đầu vào - `y2`: tọa độ y của điểm góc dưới bên phải của hộp đầu vào

input_masks (`torch.Tensor` có shape `(batch_size, image_size, image_size)`) : Mô hình SAM cũng chấp nhận các segmentation mask làm đầu vào. Mask sẽ được nhúng bởi prompt encoder để tạo ra một embedding tương ứng, sau đó được đưa vào mask decoder. Những mask này cần được người dùng cung cấp thủ công và phải có shape (`batch_size`, `image_size`, `image_size`).

image_embeddings (`torch.Tensor` có shape `(batch_size, output_channels, window_size, window_size)`) : Các embedding của ảnh, được mask decoder sử dụng để tạo ra các mask và điểm iou. Để tính toán hiệu quả bộ nhớ hơn, người dùng có thể lấy trước các embedding của ảnh bằng phương thức `get_image_embeddings`, sau đó truyền chúng vào phương thức `forward` thay vì truyền `pixel_values`.

multimask_output (`bool`, *tùy chọn*) : Trong bản triển khai và bài báo gốc, mô hình luôn xuất ra 3 mặt nạ cho mỗi ảnh (hoặc cho mỗi điểm / mỗi hộp bao nếu liên quan). Tuy nhiên, có thể chỉ xuất ra một mặt nạ duy nhất, tương ứng với mặt nạ "tốt nhất", bằng cách chỉ định `multimask_output=False`.

attention_similarity (`torch.Tensor`, *tùy chọn*) : Tensor tương đồng chú ý, được cung cấp cho bộ giải mã mặt nạ để chú ý có định hướng mục tiêu trong trường hợp mô hình được sử dụng cho cá nhân hóa như đã giới thiệu trong [PerSAM](https://huggingface.co/papers/2305.03048).

target_embedding (`torch.Tensor`, *tùy chọn*) : Embedding của khái niệm đích, được cung cấp cho mask decoder để thực hiện target-semantic prompting trong trường hợp mô hình được sử dụng cho cá nhân hóa như đã giới thiệu trong [PerSAM](https://huggingface.co/papers/2305.03048).

**Trả về:** `Sam3TrackerImageSegmentationOutput` hoặc `tuple(torch.Tensor)`

Một `Sam3TrackerImageSegmentationOutput` hoặc một tuple của `torch.Tensor` (nếu `return_dict=False` được truyền hoặc khi `config.return_dict=False`) bao gồm các thành phần khác nhau tùy thuộc vào cấu hình ([Sam3TrackerConfig](/docs/transformers/v5.23.0/vi/model_doc/sam3_tracker#transformers.Sam3TrackerConfig)) và đầu vào.

Phương thức forward của [Sam3TrackerModel](/docs/transformers/v5.23.0/vi/model_doc/sam3_tracker#transformers.Sam3TrackerModel) ghi đè lên phương thức đặc biệt `__call__`.

Mặc dù công thức cho bước truyền tiến cần được định nghĩa bên trong hàm này, bạn nên gọi instance của `Module` sau đó thay vì gọi hàm này, vì instance `Module` sẽ đảm nhận việc thực hiện các bước tiền xử lý và hậu xử lý, trong khi hàm này sẽ bỏ qua chúng một cách im lặng.

- **iou_scores** (`torch.Tensor` có hình dạng `(batch_size, point_batch_size, num_masks)`) -- Điểm số Intersection over Union (IoU) của các mask dự đoán.
- **pred_masks** (`torch.Tensor` có hình dạng `(batch_size, point_batch_size, num_masks, height, width)`) -- Các mặt nạ độ phân giải thấp được dự đoán. Đây là một alias cho `low_res_masks`. Các mặt nạ này cần được xử lý hậu kỳ bởi processor để đưa về kích thước ảnh gốc.
- **object_score_logits** (`torch.Tensor` có hình dạng `(batch_size, point_batch_size, 1)`) -- Logits cho điểm đối tượng, cho biết có đối tượng hiện diện hay không.
- **image_embeddings** (`tuple(torch.Tensor)`) -- Các đặc trưng từ FPN, được sử dụng bởi bộ giải mã mask. Đây là một tuple của `torch.Tensor` trong đó mỗi tensor có hình dạng `(batch_size, channels, height, width)`.
- **vision_hidden_states** (`tuple(torch.Tensor)`, *tuỳ chọn*, được trả về khi `output_hidden_states=True`) -- Tuple của `torch.Tensor` (một cho đầu ra của mỗi giai đoạn) có hình dạng `(batch_size, height, width, hidden_size)`. Trạng thái ẩn (hidden-states) của mô hình thị giác tại đầu ra của mỗi giai đoạn.
- **vision_attentions** (`tuple(torch.Tensor)`, *tuỳ chọn*, được trả về khi `output_attentions=True`) -- Bộ tuple của `torch.Tensor` (một cho mỗi lớp) có hình dạng `(batch_size, num_heads, sequence_length, sequence_length)`. Trọng số chú ý của mô hình thị giác.
- **mask_decoder_attentions** (`tuple(torch.Tensor)`, *tuỳ chọn*, trả về khi `output_attentions=True`) -- Tuple của `torch.Tensor` (một cho mỗi lớp) có hình dạng `(batch_size, num_heads, sequence_length, sequence_length)`. Trọng số chú ý của mask decoder.

Ví dụ:

```python
>>> 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[[transformers.Sam3TrackerModel.get_image_features]]

```python
get_image_features(pixel_values: Tensor, **kwargs: *<class 'transformers.utils.generic.TransformersKwargs'>)
```

[Nguồn](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/sam3_tracker/modeling_sam3_tracker.py#L1064)

**Tham số:**

pixel_values (`torch.Tensor`) : Giá trị pixel đầu vào có hình dạng `(batch_size, num_channels, height, width)`.

**Trả về:** `Sam3TrackerVisionEncoderOutput` hoặc `tuple(torch.Tensor)`

Một `Sam3TrackerVisionEncoderOutput` hoặc một tuple của `torch.Tensor` (nếu `return_dict=False` được truyền hoặc khi `config.return_dict=False`) bao gồm các phần tử khác nhau tùy thuộc vào cấu hình ([Sam3TrackerConfig](/docs/transformers/v5.23.0/vi/model_doc/sam3_tracker#transformers.Sam3TrackerConfig)) và đầu vào.

- **last_hidden_state** (`torch.Tensor` có hình dạng `(batch_size, height, width, hidden_size)`) -- Chuỗi các hidden-state tại đầu ra của lớp cuối cùng của mô hình.
- **pooler_output** (`torch.Tensor` có hình dạng `(batch_size, hidden_size)`) -- Trạng thái ẩn của lớp cuối cùng cho token đầu tiên của chuỗi (token phân loại) sau khi được xử lý thêm thông qua các lớp dùng cho tác vụ tiền huấn luyện bổ trợ. Ví dụ, đối với các mô hình thuộc họ BERT, giá trị này trả về token phân loại sau khi được xử lý qua một lớp tuyến tính và một hàm kích hoạt tanh. Trọng số của lớp tuyến tính được huấn luyện từ mục tiêu dự đoán câu tiếp theo (phân loại) trong quá trình tiền huấn luyện.
- **hidden_states** (`tuple(torch.Tensor)`, *tuỳ chọn*, được trả về khi `output_hidden_states=True` được truyền vào hoặc khi `config.output_hidden_states=True`) -- Bộ tuple của `torch.Tensor` (một cho đầu ra của các embedding, nếu mô hình có lớp embedding, + một cho đầu ra của mỗi lớp) có hình dạng `(batch_size, sequence_length, hidden_size)`.

  Trạng thái ẩn của mô hình tại đầu ra của mỗi lớp cùng với các đầu ra embedding ban đầu tùy chọn.
- **attentions** (`tuple(torch.Tensor)`, *tuỳ chọn*, được trả về khi `output_attentions=True` được truyền vào hoặc khi `config.output_attentions=True`) -- Bộ tuple của `torch.Tensor` (một cho mỗi lớp) có hình dạng `(batch_size, num_heads, sequence_length, sequence_length)`.

  Trọng số chú ý sau softmax của attention, được sử dụng để tính trung bình có trọng số trong các đầu self-attention.
- **fpn_hidden_states** (`tuple(torch.Tensor)`) -- Tuple của `torch.Tensor` (một tensor cho mỗi mức đặc trưng, từ độ phân giải cao xuống thấp) có hình dạng `(batch_size, hidden_size, height, width)`. Các bản đồ đặc trưng từ phần neck của Feature Pyramid Network.
- **fpn_position_encoding** (`tuple(torch.Tensor)`) -- Tuple của `torch.Tensor` (một cho mỗi mức đặc trưng, từ độ phân giải cao xuống thấp) có hình dạng `(batch_size, hidden_size, height, width)`. Các mã hóa vị trí tương ứng với `fpn_hidden_states`.

Ví dụ:

```python
```

## Sam3TrackerPreTrainedModel[[transformers.Sam3TrackerPreTrainedModel]]

#### transformers.Sam3TrackerPreTrainedModel[[transformers.Sam3TrackerPreTrainedModel]]

```python
transformers.Sam3TrackerPreTrainedModel(config: PreTrainedConfig, *inputs, **kwargs)
```

[Nguồn](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/sam3_tracker/modeling_sam3_tracker.py#L117)

**Tham số:**

config ([PreTrainedConfig](/docs/transformers/v5.23.0/vi/main_classes/configuration#transformers.PreTrainedConfig)) : Lớp cấu hình mô hình chứa tất cả các tham số của mô hình. Khởi tạo bằng tệp cấu hình sẽ không tải trọng số liên quan đến mô hình, chỉ tải cấu hình. Xem phương thức [from_pretrained()](/docs/transformers/v5.23.0/vi/main_classes/model#transformers.PreTrainedModel.from_pretrained) để tải trọng số mô hình.

Mô hình Segment Anything 3 (SAM 3) để tạo các mặt nạ phân đoạn, dựa trên ảnh đầu vào cùng các điểm và nhãn đầu vào, hộp hoặc mặt nạ.

#### forward[[transformers.Sam3TrackerPreTrainedModel.forward]]

```python
forward(*args, **kwargs)
```

Một giá trị giả lập cho một đường dẫn có dấu chấm (ví dụ: `torch.float32`): các chuỗi truy cập thuộc tính, các lời gọi hoạt động như các decorator pass-through, `repr` là đường dẫn có dấu chấm, và việc sử dụng nó như một lớp cơ sở sẽ thay thế bằng một lớp cơ sở `type` thông thường (PEP 560 `__mro_entries__`), do đó các lớp con thực sự vẫn giữ nguyên metaclass bình thường và `inspect.signature` sẽ đọc `__init__` thực của chúng thay vì của một mock.

