Reference for ultralytics/models/sam/modules/utils.py
Note
This file is available at https://github.com/ultralytics/ultralytics/blob/main/ultralytics/models/sam/modules/utils.py. If you spot a problem please help fix it by contributing a Pull Request 🛠️. Thank you 🙏!
ultralytics.models.sam.modules.utils.select_closest_cond_frames
Selects the closest conditioning frames to a given frame index.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
frame_idx
|
int
|
Current frame index. |
required |
cond_frame_outputs
|
Dict[int, Any]
|
Dictionary of conditioning frame outputs keyed by frame indices. |
required |
max_cond_frame_num
|
int
|
Maximum number of conditioning frames to select. |
required |
Returns:
Type | Description |
---|---|
Tuple[Dict[int, Any], Dict[int, Any]]
|
A tuple containing two dictionaries: - selected_outputs: Selected items from cond_frame_outputs. - unselected_outputs: Items not selected from cond_frame_outputs. |
Examples:
>>> frame_idx = 5
>>> cond_frame_outputs = {1: "a", 3: "b", 7: "c", 9: "d"}
>>> max_cond_frame_num = 2
>>> selected, unselected = select_closest_cond_frames(frame_idx, cond_frame_outputs, max_cond_frame_num)
>>> print(selected)
{3: 'b', 7: 'c'}
>>> print(unselected)
{1: 'a', 9: 'd'}
Source code in ultralytics/models/sam/modules/utils.py
ultralytics.models.sam.modules.utils.get_1d_sine_pe
Generates 1D sinusoidal positional embeddings for given positions and dimensions.
Source code in ultralytics/models/sam/modules/utils.py
ultralytics.models.sam.modules.utils.init_t_xy
Initializes 1D and 2D coordinate tensors for a grid of specified dimensions.
Source code in ultralytics/models/sam/modules/utils.py
ultralytics.models.sam.modules.utils.compute_axial_cis
Computes axial complex exponential positional encodings for 2D spatial positions in a grid.
Source code in ultralytics/models/sam/modules/utils.py
ultralytics.models.sam.modules.utils.reshape_for_broadcast
Reshapes frequency tensor for broadcasting with input tensor, ensuring dimensional compatibility.
Source code in ultralytics/models/sam/modules/utils.py
ultralytics.models.sam.modules.utils.apply_rotary_enc
apply_rotary_enc(
xq: torch.Tensor,
xk: torch.Tensor,
freqs_cis: torch.Tensor,
repeat_freqs_k: bool = False,
)
Applies rotary positional encoding to query and key tensors using complex-valued frequency components.
Source code in ultralytics/models/sam/modules/utils.py
ultralytics.models.sam.modules.utils.window_partition
Partitions input tensor into non-overlapping windows with padding if needed.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
x
|
Tensor
|
Input tensor with shape (B, H, W, C). |
required |
window_size
|
int
|
Size of each window. |
required |
Returns:
Type | Description |
---|---|
Tuple[Tensor, Tuple[int, int]]
|
A tuple containing: - windows (torch.Tensor): Partitioned windows with shape (B * num_windows, window_size, window_size, C). - (Hp, Wp) (Tuple[int, int]): Padded height and width before partition. |
Examples:
>>> x = torch.randn(1, 16, 16, 3)
>>> windows, (Hp, Wp) = window_partition(x, window_size=4)
>>> print(windows.shape, Hp, Wp)
torch.Size([16, 4, 4, 3]) 16 16
Source code in ultralytics/models/sam/modules/utils.py
ultralytics.models.sam.modules.utils.window_unpartition
Unpartitions windowed sequences into original sequences and removes padding.
This function reverses the windowing process, reconstructing the original input from windowed segments and removing any padding that was added during the windowing process.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
windows
|
Tensor
|
Input tensor of windowed sequences with shape (B * num_windows, window_size, window_size, C), where B is the batch size, num_windows is the number of windows, window_size is the size of each window, and C is the number of channels. |
required |
window_size
|
int
|
Size of each window. |
required |
pad_hw
|
Tuple[int, int]
|
Padded height and width (Hp, Wp) of the input before windowing. |
required |
hw
|
Tuple[int, int]
|
Original height and width (H, W) of the input before padding and windowing. |
required |
Returns:
Type | Description |
---|---|
Tensor
|
Unpartitioned sequences with shape (B, H, W, C), where B is the batch size, H and W are the original height and width, and C is the number of channels. |
Examples:
>>> windows = torch.rand(32, 8, 8, 64) # 32 windows of size 8x8 with 64 channels
>>> pad_hw = (16, 16) # Padded height and width
>>> hw = (15, 14) # Original height and width
>>> x = window_unpartition(windows, window_size=8, pad_hw=pad_hw, hw=hw)
>>> print(x.shape)
torch.Size([1, 15, 14, 64])
Source code in ultralytics/models/sam/modules/utils.py
ultralytics.models.sam.modules.utils.get_rel_pos
Extracts relative positional embeddings based on query and key sizes.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
q_size
|
int
|
Size of the query. |
required |
k_size
|
int
|
Size of the key. |
required |
rel_pos
|
Tensor
|
Relative position embeddings with shape (L, C), where L is the maximum relative distance and C is the embedding dimension. |
required |
Returns:
Type | Description |
---|---|
Tensor
|
Extracted positional embeddings according to relative positions, with shape (q_size, k_size, C). |
Examples:
>>> q_size, k_size = 8, 16
>>> rel_pos = torch.randn(31, 64) # 31 = 2 * max(8, 16) - 1
>>> extracted_pos = get_rel_pos(q_size, k_size, rel_pos)
>>> print(extracted_pos.shape)
torch.Size([8, 16, 64])
Source code in ultralytics/models/sam/modules/utils.py
ultralytics.models.sam.modules.utils.add_decomposed_rel_pos
add_decomposed_rel_pos(
attn: torch.Tensor,
q: torch.Tensor,
rel_pos_h: torch.Tensor,
rel_pos_w: torch.Tensor,
q_size: Tuple[int, int],
k_size: Tuple[int, int],
) -> torch.Tensor
Adds decomposed Relative Positional Embeddings to the attention map.
This function calculates and applies decomposed Relative Positional Embeddings as described in the MVITv2 paper. It enhances the attention mechanism by incorporating spatial relationships between query and key positions.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
attn
|
Tensor
|
Attention map with shape (B, q_h * q_w, k_h * k_w). |
required |
q
|
Tensor
|
Query tensor in the attention layer with shape (B, q_h * q_w, C). |
required |
rel_pos_h
|
Tensor
|
Relative position embeddings for height axis with shape (Lh, C). |
required |
rel_pos_w
|
Tensor
|
Relative position embeddings for width axis with shape (Lw, C). |
required |
q_size
|
Tuple[int, int]
|
Spatial sequence size of query q as (q_h, q_w). |
required |
k_size
|
Tuple[int, int]
|
Spatial sequence size of key k as (k_h, k_w). |
required |
Returns:
Type | Description |
---|---|
Tensor
|
Updated attention map with added relative positional embeddings, shape (B, q_h * q_w, k_h * k_w). |
Examples:
>>> B, C, q_h, q_w, k_h, k_w = 1, 64, 8, 8, 8, 8
>>> attn = torch.rand(B, q_h * q_w, k_h * k_w)
>>> q = torch.rand(B, q_h * q_w, C)
>>> rel_pos_h = torch.rand(2 * max(q_h, k_h) - 1, C)
>>> rel_pos_w = torch.rand(2 * max(q_w, k_w) - 1, C)
>>> q_size, k_size = (q_h, q_w), (k_h, k_w)
>>> updated_attn = add_decomposed_rel_pos(attn, q, rel_pos_h, rel_pos_w, q_size, k_size)
>>> print(updated_attn.shape)
torch.Size([1, 64, 64])