### Run Training Script

Source: https://github.com/jeff-zilence/transgeo2022/blob/main/README.md

Execute this shell script to start the training process. Ensure you have specified the correct GPUs in 'train.py' and set the desired dataset using the '--dataset' argument.

```shell
sh run_CVUSA.sh
```

--------------------------------

### Run Training Pipeline (Stage-1 CVUSA)

Source: https://context7.com/jeff-zilence/transgeo2022/llms.txt

Command to initiate the first stage of training for the CVUSA dataset using SAM and ASAM optimization. Ensure distributed training is configured correctly.

```bash
python -u train.py \
  --lr 0.0001 \
  --batch-size 32 \
  --dist-url 'tcp://localhost:10001' \
  --multiprocessing-distributed \
  --world-size 1 --rank 0 \
  --epochs 100 \
  --save_path ./result \
  --op sam --asam --rho 2.5 \
  --wd 0.03 \
  --mining \
  --dataset cvusa \
  --cos \
  --dim 1000
```

--------------------------------

### TransGeo Model Inference (Stage-1 and Stage-2)

Source: https://context7.com/jeff-zilence/transgeo2022/llms.txt

Demonstrates how to instantiate and use the TransGeo model for both Stage-1 (global descriptors) and Stage-2 (attention-guided cropping) inference. Ensure the correct arguments are passed for dataset defaults and cropping behavior.

```python
import argparse
import torch
from model.TransGeo import TransGeo

# Simulate args as parsed by train.py
args = argparse.Namespace(
    dataset='cvusa',
    dim=1000,
    sat_res=0,      # 0 = use dataset default (256×256)
    fov=0,          # 0 = full 360° panorama
    crop=False,     # Stage-1: no nonuniform cropping
)

model = TransGeo(args=args)
model = torch.nn.DataParallel(model).cuda()
model.eval()

# Stage-1 inference: full satellite image, no attention map
batch = 4
img_ground = torch.randn(batch, 3, 112, 616).cuda()   # ground query
img_sat    = torch.randn(batch, 3, 256, 256).cuda()   # satellite reference

with torch.no_grad():
    embed_q, embed_k = model(im_q=img_ground, im_k=img_sat, delta=None)
    # embed_q: [4, 1000], embed_k: [4, 1000]
    print(embed_q.shape, embed_k.shape)
    # torch.Size([4, 1000]) torch.Size([4, 1000])

# Stage-2 inference: pass attention map to crop satellite patches
args.crop = True
model2 = TransGeo(args=args)
model2 = torch.nn.DataParallel(model2).cuda()
model2.eval()

atten = torch.rand(batch, 3, 256, 256).cuda()  # attention map from stage-1 scan
with torch.no_grad():
    embed_q2, embed_k2 = model2(im_q=img_ground, im_k=img_sat, delta=None, atten=atten)
    print(embed_q2.shape, embed_k2.shape)
    # torch.Size([4, 1000]) torch.Size([4, 1000])
```

--------------------------------

### Load CVUSA Datasets for Query and Reference

Source: https://context7.com/jeff-zilence/transgeo2022/llms.txt

Initializes CVUSA datasets for query and reference in test mode. Ensure the root directory and arguments are correctly set.

```python
val_query_ds = CVUSA(mode='test_query', root='/data/CVUSA/', args=args)
val_ref_ds   = CVUSA(mode='test_reference', root='/data/CVUSA/', args=args)
```

--------------------------------

### Run Training Pipeline (Stage-2 CVUSA with nonuniform crop)

Source: https://context7.com/jeff-zilence/transgeo2022/llms.txt

Command to run the second stage of training for CVUSA, resuming from previous weights and enabling nonuniform cropping. Adjust learning rate and epochs as needed.

```bash
python -u train.py \
  --lr 0.00001 \
  --batch-size 32 \
  --dist-url 'tcp://localhost:10001' \
  --multiprocessing-distributed \
  --world-size 1 --rank 0 \
  --epochs 50 \
  --resume ./result/checkpoint.pth.tar \
  --save_path ./result \
  --op sam --asam --rho 2.5 \
  --wd 0.03 \
  --mining \
  --dataset cvusa \
  --cos \
  --dim 1000 \
  --sat_res 320 \
  --crop
```

--------------------------------

### Load CVACT Dataset for Training

Source: https://context7.com/jeff-zilence/transgeo2022/llms.txt

Initializes the CVACT dataset for training. `print_bool=True` enables reporting of missing files and dataset sizes. The root directory should point to the ANU_data_small folder.

```python
args = argparse.Namespace(sat_res=0, fov=0, crop=False, resume='')

train_ds = CVACT(
    mode='train',
    root='/data/CVACT/ANU_data_small/',
    print_bool=True,
    args=args
)
```

--------------------------------

### Create DataLoaders for CVUSA Query and Reference

Source: https://context7.com/jeff-zilence/transgeo2022/llms.txt

Sets up DataLoader instances for the CVUSA query and reference datasets with specified batch sizes and number of workers. `shuffle` is set to False for validation.

```python
val_q_loader = DataLoader(val_query_ds, batch_size=32, shuffle=False, num_workers=8)
val_r_loader = DataLoader(val_ref_ds,   batch_size=64, shuffle=False, num_workers=8)
```

--------------------------------

### TransGeo Model Usage

Source: https://context7.com/jeff-zilence/transgeo2022/llms.txt

Demonstrates how to instantiate and use the TransGeo model for both stage-1 and stage-2 inference. It shows how to pass ground and satellite images to generate embeddings, and how to optionally use attention maps for stage-2 cropping.

```APIDOC
## TransGeo(args)

### Description
Dual-branch transformer model for cross-view geo-localization. It wraps two DistilledVisionTransformer (DeiT-S) encoders: `query_net` for ground-level images and `reference_net` for satellite images. Image sizes are automatically set per dataset, but can be overridden.

### Method
```python
import argparse
import torch
from model.TransGeo import TransGeo

# Simulate args as parsed by train.py
args = argparse.Namespace(
    dataset='cvusa',
    dim=1000,
    sat_res=0,      # 0 = use dataset default (256×256)
    fov=0,          # 0 = full 360° panorama
    crop=False,     # Stage-1: no nonuniform cropping
)

model = TransGeo(args=args)
model = torch.nn.DataParallel(model).cuda()
model.eval()

# Stage-1 inference: full satellite image, no attention map
batch = 4
img_ground = torch.randn(batch, 3, 112, 616).cuda()   # ground query
img_sat    = torch.randn(batch, 3, 256, 256).cuda()   # satellite reference

with torch.no_grad():
    embed_q, embed_k = model(im_q=img_ground, im_k=img_sat, delta=None)
    # embed_q: [4, 1000], embed_k: [4, 1000]
    print(embed_q.shape, embed_k.shape)
    # torch.Size([4, 1000]) torch.Size([4, 1000])

# Stage-2 inference: pass attention map to crop satellite patches
args.crop = True
model2 = TransGeo(args=args)
model2 = torch.nn.DataParallel(model2).cuda()
model2.eval()

atten = torch.rand(batch, 3, 256, 256).cuda()  # attention map from stage-1 scan
with torch.no_grad():
    embed_q2, embed_k2 = model2(im_q=img_ground, im_k=img_sat, delta=None, atten=atten)
    print(embed_q2.shape, embed_k2.shape)
    # torch.Size([4, 1000]) torch.Size([4, 1000])
```
```

--------------------------------

### Create DataLoader for CVACT Training

Source: https://context7.com/jeff-zilence/transgeo2022/llms.txt

Sets up a DataLoader for the CVACT training dataset with a batch size of 32, shuffling enabled, and `drop_last=True`. `num_workers` is set to 8.

```python
loader = DataLoader(train_ds, batch_size=32, shuffle=True, num_workers=8, drop_last=True)
```

--------------------------------

### Distributed Mining Sampler Usage

Source: https://context7.com/jeff-zilence/transgeo2022/llms.txt

Demonstrates how to use the DistributedMiningSampler for distributed training. It covers initialization, epoch setting, updating with embeddings, and loading/saving sampler state for resumable training.

```python
sampler = DistributedMiningSampler(
    dataset=train_ds,
    batch_size=args.batch_size,   # total across all GPUs
    dim=args.dim,
    save_path='./result'
)

loader = torch.utils.data.DataLoader(
    train_ds, batch_size=args.batch_size, sampler=sampler,
    num_workers=8, pin_memory=True, drop_last=True
)

# During training loop:
for epoch in range(10):
    sampler.set_epoch(epoch)
    sampler.update_epoch()        # regenerates hard-negative index order
    for img_q, img_k, idx_q, idx_k, delta, atten in loader:
        # ... forward pass to get embed_q, embed_k ...
        embed_q = torch.randn(args.batch_size, args.dim).numpy()
        embed_k = torch.randn(args.batch_size, args.dim).numpy()
        idxs    = idx_k.numpy()
        sampler.update(embed_k, embed_q, idxs)   # writes to queue

# Persist queue for resumable training
# Saved automatically at: ./result/queue.npy, ./result/queue_counter.npy
sampler_new = DistributedMiningSampler(train_ds, batch_size=32, dim=1000, save_path='./result')
sampler_new.load('./result')      # restores queue state
```

--------------------------------

### Create DataLoader for VIGOR Training

Source: https://context7.com/jeff-zilence/transgeo2022/llms.txt

Sets up a DataLoader for the VIGOR training dataset with a batch size of 16, shuffling enabled, and `drop_last=True`. `num_workers` is set to 8.

```python
loader = DataLoader(train_ds, batch_size=16, shuffle=True, num_workers=8, drop_last=True)
```

--------------------------------

### Initialize DistributedMiningSampler for CVUSA Training

Source: https://context7.com/jeff-zilence/transgeo2022/llms.txt

Sets up the `DistributedMiningSampler` for the CVUSA training dataset. This sampler is designed for online hard-negative mining in distributed training environments. Note: `torch.distributed` must be initialized prior to use.

```python
import argparse, torch
from dataset.CVUSA import CVUSA
from dataset.global_sampler import DistributedMiningSampler

args = argparse.Namespace(sat_res=0, fov=0, crop=False, resume='',
                          batch_size=32, dim=1000)

train_ds = CVUSA(mode='train', root='/data/CVUSA/', args=args)

# Requires torch.distributed to be initialized first
```

--------------------------------

### Iterate through CVUSA Query DataLoader

Source: https://context7.com/jeff-zilence/transgeo2022/llms.txt

Demonstrates iterating through the CVUSA query DataLoader to inspect image and index shapes. The loop breaks after the first batch.

```python
for img_q, idx, label in val_q_loader:
    print(img_q.shape, idx.shape)  # torch.Size([32, 3, 112, 616]) torch.Size([32])
    break
```

--------------------------------

### Load VIGOR Dataset for Same-Area Training

Source: https://context7.com/jeff-zilence/transgeo2022/llms.txt

Initializes the VIGOR dataset for training in `same_area=True` mode, using all four cities for both training and testing. `print_bool=True` enables verbose loading information.

```python
args = argparse.Namespace(sat_res=0, fov=0, crop=False, resume='')

train_ds = VIGOR(
    mode='train',
    root='/data/VIGOR/',
    same_area=True,
    print_bool=True,
    args=args
)
```

--------------------------------

### SAM/ASAM Optimizer for Sharpness-Aware Minimization

Source: https://context7.com/jeff-zilence/transgeo2022/llms.txt

Sharpness-Aware Minimization (SAM) optimizer that wraps a base optimizer to find flatter minima. It requires two forward-backward passes per iteration. ASAM (adaptive SAM) scales perturbations by parameter magnitudes.

```python
import torch
from criterion.sam import SAM

model = torch.nn.Linear(128, 10).cuda()
params = [p for p in model.parameters() if p.requires_grad]

# Standard SAM wrapping AdamW
optimizer = SAM(
    params,
    base_optimizer=torch.optim.AdamW,
    rho=2.5,
    adaptive=True,    # ASAM mode
    lr=1e-4,
    betas=(0.9, 0.999),
    eps=1e-8,
    weight_decay=0.03,
)

criterion = torch.nn.CrossEntropyLoss()
x = torch.randn(16, 128).cuda()
y = torch.randint(0, 10, (16,)).cuda()

# First forward-backward pass
pred = model(x)
loss = criterion(pred, y)
loss.backward()
optimizer.first_step(zero_grad=True)  # perturb weights

# Second forward-backward pass (at perturbed weights)
pred2 = model(x)
loss2 = criterion(pred2, y)
loss2.backward()
optimizer.second_step(zero_grad=True)  # restore + update

print(f"Loss (pass 1): {loss.item():.4f}")
print(f"Loss (pass 2): {loss2.item():.4f}")

# Save and reload optimizer state
torch.save(optimizer.state_dict(), 'sam_state.pt')
optimizer.load_state_dict(torch.load('sam_state.pt'))
```

--------------------------------

### Run VIGOR Training Scripts

Source: https://context7.com/jeff-zilence/transgeo2022/llms.txt

Commands to execute shell scripts for VIGOR dataset training. These scripts likely encapsulate complex configurations for different VIGOR training scenarios.

```bash
bash run_VIGOR.sh
```

```bash
bash run_VIGOR_cross.sh
```

```bash
bash run_CVUSA_fov90.sh
```

--------------------------------

### SAM(params, base_optimizer, rho, adaptive)

Source: https://context7.com/jeff-zilence/transgeo2022/llms.txt

Sharpness-Aware Minimization optimizer. Wraps any base PyTorch optimizer and implements a two-step update: first_step perturbs weights to the local loss maximum, then second_step restores the original weights and performs the true gradient step at the perturbed point.

```APIDOC
## SAM(params, base_optimizer, rho, adaptive)

### Description
Sharpness-Aware Minimization optimizer. Wraps any base PyTorch optimizer and implements a two-step update: `first_step` perturbs weights to the local loss maximum (climbing by `rho`-scaled gradient), then `second_step` restores the original weights and performs the true gradient step at the perturbed point. When `adaptive=True` this becomes ASAM, scaling the perturbation by parameter magnitudes. SAM requires two forward-backward passes per iteration.

### Parameters
- **params**: (iterable) - Iterable of parameters to optimize.
- **base_optimizer**: (torch.optim.Optimizer) - The base optimizer to wrap.
- **rho**: (float) - The perturbation size for SAM.
- **adaptive**: (bool) - If True, enables ASAM mode.

### Method
`optimizer.first_step(zero_grad=True)`

### Description
Performs the first step of the SAM update, perturbing the weights.

### Parameters
- **zero_grad**: (bool) - If True, zeros the gradients after the perturbation.

### Method
`optimizer.second_step(zero_grad=True)`

### Description
Performs the second step of the SAM update, restoring weights and performing the true gradient step.

### Parameters
- **zero_grad**: (bool) - If True, zeros the gradients after the weight update.

### Request Example
```python
import torch
from criterion.sam import SAM

model = torch.nn.Linear(128, 10).cuda()
params = [p for p in model.parameters() if p.requires_grad]

# Standard SAM wrapping AdamW
optimizer = SAM(
    params,
    base_optimizer=torch.optim.AdamW,
    rho=2.5,
    adaptive=True,    # ASAM mode
    lr=1e-4,
    betas=(0.9, 0.999),
    eps=1e-8,
    weight_decay=0.03,
)

criterion = torch.nn.CrossEntropyLoss()
x = torch.randn(16, 128).cuda()
y = torch.randint(0, 10, (16,)).cuda()

# First forward-backward pass
pred = model(x)
loss = criterion(pred, y)
loss.backward()
optimizer.first_step(zero_grad=True)  # perturb weights

# Second forward-backward pass (at perturbed weights)
pred2 = model(x)
loss2 = criterion(pred2, y)
loss2.backward()
optimizer.second_step(zero_grad=True)  # restore + update

print(f"Loss (pass 1): {loss.item():.4f}")
print(f"Loss (pass 2): {loss2.item():.4f}")

# Save and reload optimizer state
torch.save(optimizer.state_dict(), 'sam_state.pt')
optimizer.load_state_dict(torch.load('sam_state.pt'))
```

### Response Example
```
Loss (pass 1): 2.3026
Loss (pass 2): 2.3026
```
```

--------------------------------

### Initialize CVUSA Dataset with Limited Field of View (FoV)

Source: https://context7.com/jeff-zilence/transgeo2022/llms.txt

Creates a CVUSA dataset instance configured for training with a limited field of view (90 degrees). This variant is used for cameras with a narrower view.

```python
args_fov = argparse.Namespace(sat_res=0, fov=90, crop=False, resume='')
train_fov = CVUSA(mode='train', root='/data/CVUSA/', args=args_fov)
```

--------------------------------

### CVUSA Dataset Loader for Training

Source: https://context7.com/jeff-zilence/transgeo2022/llms.txt

Loads paired satellite and ground images from the CVUSA dataset for training. Supports different modes for data retrieval and optional FOV cropping. Ensure the dataset is downloaded and paths are correctly set.

```python
import argparse
from dataset.CVUSA import CVUSA
from torch.utils.data import DataLoader

args = argparse.Namespace(sat_res=0, fov=0, crop=False, resume='')

# Training loader
train_dataset = CVUSA(
    mode='train',
    root='/data/CVUSA/',
    same_area=True,
    print_bool=True,
    args=args
)
# CVUSA: load splits/train-19zl.csv  data_size = 35532

train_loader = DataLoader(train_dataset, batch_size=32, shuffle=True,
                          num_workers=8, pin_memory=True, drop_last=True)

for img_q, img_k, idx_q, idx_k, delta, atten in train_loader:
    print(img_q.shape)   # torch.Size([32, 3, 112, 616])
    print(img_k.shape)   # torch.Size([32, 3, 256, 256])
    break
```

--------------------------------

### DistilledVisionTransformer (DeiT-S) Initialization and Forward Pass

Source: https://context7.com/jeff-zilence/transgeo2022/llms.txt

Initializes a flexible-resolution DeiT-Small model and performs a forward pass for feature extraction. The `save` attribute can be set to a directory to save attention maps during inference.

```python
import torch
from model.Deit import deit_small_distilled_patch16_224

# Ground branch: rectangular image [112×616] → 7×38 patch grid
query_net = deit_small_distilled_patch16_224(
    pretrained=True,
    img_size=(112, 616),
    num_classes=1000
)
query_net.eval()

x_grd = torch.randn(2, 3, 112, 616)
with torch.no_grad():
    out = query_net(x_grd)          # plain forward, no attention
    print(out.shape)                # torch.Size([2, 1000])

# Save attention maps (stage-1 scan mode)
import os, tempfile
save_dir = tempfile.mkdtemp()
query_net.save = save_dir           # triggers forward_features_save()
indexes = torch.tensor([0, 1])
with torch.no_grad():
    out = query_net(x_grd, indexes=indexes)
    # Saves attention maps as PNGs: {save_dir}/0.png, {save_dir}/1.png
    print(os.listdir(save_dir))     # ['0.png', '1.png']
```

--------------------------------

### Evaluate Model with Pretrained Weights

Source: https://context7.com/jeff-zilence/transgeo2022/llms.txt

Command to evaluate the trained model using pretrained weights. This command is used for assessing performance on the validation set after training.

```bash
python -u train.py \
  --evaluate \
  --resume ./result/model_best.pth.tar \
  --save_path ./result \
  --dataset cvusa \
  --dim 1000 \
  --sat_res 320 \
  --crop
```

--------------------------------

### CVUSA(mode, root, same_area, args)

Source: https://context7.com/jeff-zilence/transgeo2022/llms.txt

CVUSA cross-view dataset loader. Loads paired satellite and ground panorama images from CVUSA split CSV files. Supports different modes for training, validation, and testing.

```APIDOC
## CVUSA(mode, root, same_area, args)

### Description
CVUSA cross-view dataset loader. Loads paired satellite (750×750 original, resized to 256×256) and ground panorama (224×1232 original, resized to 112×616) images from CVUSA split CSV files (`splits/train-19zl.csv`, `splits/val-19zl.csv`). Supports four modes: `'train'` returns `(img_query, img_reference, idx, idx, 0, atten_or_0)`, `'scan_val'` returns paired images for attention scanning, `'test_query'` returns ground images with index, and `'test_reference'` returns satellite images optionally with their attention maps. Setting `args.fov != 0` applies a random horizontal rotation followed by cropping to the specified field-of-view.

### Parameters
- **mode**: (str) - The dataset mode ('train', 'scan_val', 'test_query', 'test_reference').
- **root**: (str) - The root directory of the CVUSA dataset.
- **same_area**: (bool) - If True, loads pairs from the same geographical area.
- **args**: (argparse.Namespace) - Namespace containing additional arguments like `fov`.

### Returns
- **img_query**: (torch.Tensor) - Query image tensor.
- **img_reference**: (torch.Tensor) - Reference image tensor.
- **idx**: (torch.Tensor) - Indices of the images.
- **delta**: (torch.Tensor) - Delta value (usually 0 for train mode).
- **atten_or_0**: (torch.Tensor) - Attention map or 0.

### Request Example
```python
import argparse
from dataset.CVUSA import CVUSA
from torch.utils.data import DataLoader

args = argparse.Namespace(sat_res=0, fov=0, crop=False, resume='')

# Training loader
train_dataset = CVUSA(
    mode='train',
    root='/data/CVUSA/',
    same_area=True,
    print_bool=True,
    args=args
)
# CVUSA: load splits/train-19zl.csv  data_size = 35532

train_loader = DataLoader(train_dataset, batch_size=32, shuffle=True,
                          num_workers=8, pin_memory=True, drop_last=True)

for img_q, img_k, idx_q, idx_k, delta, atten in train_loader:
    print(img_q.shape)   # torch.Size([32, 3, 112, 616])
    print(img_k.shape)   # torch.Size([32, 3, 256, 256])
    break
```

### Response Example
```
torch.Size([32, 3, 112, 616])
torch.Size([32, 3, 256, 256])
```
```

--------------------------------

### Inspect VIGOR Training Batch Shapes

Source: https://context7.com/jeff-zilence/transgeo2022/llms.txt

Iterates through the VIGOR training DataLoader to print the shapes of query images, key images, and GPS deltas. The loop breaks after the first batch.

```python
for img_q, img_k, idx_q, idx_k, delta, atten in loader:
    print(img_q.shape)   # torch.Size([16, 3, 320, 640])
    print(img_k.shape)   # torch.Size([16, 3, 320, 320])
    print(delta.shape)   # torch.Size([16, 2])  GPS delta [lat, lng]
    break
```

--------------------------------

### Compute Retrieval Recall with Accuracy Utility

Source: https://context7.com/jeff-zilence/transgeo2022/llms.txt

Python code demonstrating the usage of the accuracy utility function for computing retrieval recall. It simulates feature vectors and labels, then calls the accuracy function.

```python
import numpy as np
from train import accuracy

# Simulate features for 1000 query / 10000 reference images
N, M, D = 1000, 10000, 1000
query_features     = np.random.randn(N, D).astype(np.float32)
reference_features = np.random.randn(M, D).astype(np.float32)
# query_labels[i] = index into reference_features of the true match
query_labels = np.random.randint(0, M, size=N)

top1, top5 = accuracy(query_features, reference_features, query_labels, topk=[1, 5, 10])
# Percentage-top1:0.10, top5:0.50, top10:1.00, top1%:10.01, time:X.Xs
print(f"Top-1 recall: {top1:.2f}%")
print(f"Top-5 recall: {top5:.2f}%")

# Save descriptors during evaluation (--evaluate flag sets this automatically)
np.save('./result/grd_global_descriptor.npy', query_features)
np.save('sat_global_descriptor.npy', reference_features)
# Reload for offline meter-level evaluation (VIGOR)
grd = np.load('./result/grd_global_descriptor.npy')
sat = np.load('sat_global_descriptor.npy')
print(grd.shape, sat.shape)  # (N, 1000), (M, 1000)
```

--------------------------------

### Initialize VIGOR Datasets for Cross-Area Evaluation

Source: https://context7.com/jeff-zilence/transgeo2022/llms.txt

Loads VIGOR datasets for cross-area evaluation in test query and test reference modes. `same_area` is set to `False`.

```python
val_query_ds = VIGOR(mode='test_query', root='/data/VIGOR/', same_area=False, args=args)
val_ref_ds   = VIGOR(mode='test_reference', root='/data/VIGOR/', same_area=False, args=args)
```

--------------------------------

### Inspect CVACT Training Batch Shapes

Source: https://context7.com/jeff-zilence/transgeo2022/llms.txt

Iterates through the CVACT training DataLoader to print the shapes of query and key images. The loop breaks after the first batch.

```python
for img_q, img_k, idx_q, idx_k, _, atten in loader:
    print(img_q.shape)  # torch.Size([32, 3, 112, 616])
    print(img_k.shape)  # torch.Size([32, 3, 256, 256])
    break
```

--------------------------------

### SoftTripletBiLoss(margin, alpha)

Source: https://context7.com/jeff-zilence/transgeo2022/llms.txt

Bidirectional soft triplet loss with cosine similarity. Computes the weighted soft-margin triplet loss in both directions (query→reference and reference→query) and averages them. Within a batch of size n, all diagonal pairs are positives; the remaining n*(n-1) pairs are negatives.

```APIDOC
## SoftTripletBiLoss(margin, alpha)

### Description
Bidirectional soft triplet loss with cosine similarity. Computes the weighted soft-margin triplet loss in both directions (query→reference and reference→query) and averages them. Within a batch of size `n`, all diagonal pairs are positives; the remaining `n*(n-1)` pairs are negatives. The loss for each positive is `mean(log(1 + exp(alpha * (neg_sim - pos_sim))))` over its `n-1` negatives, where `alpha=20` by default. The bidirectional formulation ensures both embeddings are jointly trained.

### Parameters
- **margin**: (float) - Margin for the triplet loss.
- **alpha**: (float) - Scaling factor for the loss calculation.

### Method
`criterion(embed_q, embed_k)`

### Parameters
- **embed_q**: (torch.Tensor) - Query embeddings.
- **embed_k**: (torch.Tensor) - Reference embeddings.

### Returns
- **loss**: (torch.Tensor) - The computed bidirectional soft triplet loss.
- **mean_pos_sim**: (torch.Tensor) - The average similarity between positive pairs.
- **mean_neg_sim**: (torch.Tensor) - The average similarity between negative pairs.

### Request Example
```python
import torch
from criterion.soft_triplet import SoftTripletBiLoss

criterion = SoftTripletBiLoss(alpha=20).cuda()

# Simulate a batch of 8 paired embeddings (before normalization)
batch_size = 8
dim = 1000
embed_q = torch.randn(batch_size, dim).cuda()  # ground embeddings
embed_k = torch.randn(batch_size, dim).cuda()  # satellite embeddings

loss, mean_pos_sim, mean_neg_sim = criterion(embed_q, embed_k)

print(f"Loss:         {loss.item():.4f}")
print(f"Mean pos sim: {mean_pos_sim:.4f}")   # higher = better alignment
print(f"Mean neg sim: {mean_neg_sim:.4f}")   # lower = better separation
```

### Response Example
```
Loss:         2.7731
Mean pos sim: 0.0213
Mean neg sim: 0.0024
```
```

--------------------------------

### SoftTripletBiLoss for Bidirectional Embedding Training

Source: https://context7.com/jeff-zilence/transgeo2022/llms.txt

Implements a bidirectional soft-margin triplet loss using cosine similarity. This loss function averages the loss computed in both query-to-reference and reference-to-query directions, ensuring joint training of embeddings. It requires embeddings to be normalized before use.

```python
import torch
from criterion.soft_triplet import SoftTripletBiLoss

criterion = SoftTripletBiLoss(alpha=20).cuda()

# Simulate a batch of 8 paired embeddings (before normalization)
batch_size = 8
dim = 1000
embed_q = torch.randn(batch_size, dim).cuda()  # ground embeddings
embed_k = torch.randn(batch_size, dim).cuda()  # satellite embeddings

loss, mean_pos_sim, mean_neg_sim = criterion(embed_q, embed_k)

print(f"Loss:         {loss.item():.4f}")
print(f"Mean pos sim: {mean_pos_sim:.4f}")   # higher = better alignment
print(f"Mean neg sim: {mean_neg_sim:.4f}")   # lower = better separation
# Example output:
# Loss:         2.7731
# Mean pos sim: 0.0213
# Mean neg sim: 0.0024

# Backprop
optimizer = torch.optim.Adam(list(embed_q), lr=1e-4)  # placeholder
loss.backward()
```

--------------------------------

### Calculate GPS Distance using VIGOR Utilities

Source: https://context7.com/jeff-zilence/transgeo2022/llms.txt

Demonstrates the usage of `gps2distance` from the VIGOR dataset module to calculate the distance between two sets of GPS coordinates. The result is printed in meters.

```python
from dataset.VIGOR import gps2distance, gps2distance_matrix, Lat_Lng
dist = gps2distance(40.7128, -74.0060, 40.7580, -73.9855)  # NYC to Midtown
print(f"Distance: {dist:.1f} m")  # ~5500 m
```

--------------------------------

### Non-uniform Crop Mode with DEiT

Source: https://context7.com/jeff-zilence/transgeo2022/llms.txt

Enables non-uniform cropping for image feature extraction using a distilled DEiT model. The `crop=True` argument activates the `forward_features_crop()` method, which uses attention scores to select informative patches.

```python
ref_net = deit_small_distilled_patch16_224(
    pretrained=True,
    img_size=(256, 256),
    num_classes=1000,
    crop=True                       # enables forward_features_crop()
)
ref_net.eval()
x_sat = torch.randn(2, 3, 256, 256)
atten = torch.rand(2, 3, 256, 256)  # higher values = more informative patches
with torch.no_grad():
    # crop_rate=0.64 → keeps top 64% patches by attention score
    out_crop = ref_net(x_sat, atten=atten)
    print(out_crop.shape)           # torch.Size([2, 1000])
```

--------------------------------

### DistilledVisionTransformer (DeiT Backbone)

Source: https://context7.com/jeff-zilence/transgeo2022/llms.txt

Details on the `deit_small_distilled_patch16_224` factory function, which creates a flexible-resolution DeiT-Small model. It supports pretrained weights, custom image sizes, and optional saving of attention maps.

```APIDOC
## deit_small_distilled_patch16_224(pretrained, img_size, num_classes)

### Description
Instantiates a `DistilledVisionTransformer` (DeiT-Small, patch size 16, embed dim 384, 12 layers, 6 heads). It interpolates pretrained positional embeddings to match the target grid size determined by `img_size`. If `num_classes` differs from 1000, the head weights are tiled. The forward pass averages outputs from the `cls` and `dist` tokens.

### Parameters
- **pretrained** (bool) - Whether to load pretrained weights.
- **img_size** (tuple or int) - Target image size (height, width) or a single value for square images.
- **num_classes** (int) - Number of output classes. If not 1000, head weights are tiled.

### Method
```python
import torch
from model.Deit import deit_small_distilled_patch16_224

# Ground branch: rectangular image [112×616] → 7×38 patch grid
query_net = deit_small_distilled_patch16_224(
    pretrained=True,
    img_size=(112, 616),
    num_classes=1000
)
query_net.eval()

x_grd = torch.randn(2, 3, 112, 616)
with torch.no_grad():
    out = query_net(x_grd)          # plain forward, no attention
    print(out.shape)                # torch.Size([2, 1000])

# Save attention maps (stage-1 scan mode)
import os, tempfile
save_dir = tempfile.mkdtemp()
query_net.save = save_dir           # triggers forward_features_save()
indexes = torch.tensor([0, 1])
with torch.no_grad():
    out = query_net(x_grd, indexes=indexes)
    # Saves attention maps as PNGs: {save_dir}/0.png, {save_dir}/1.png
    print(os.listdir(save_dir))     # ['0.png', '1.png']
```
```

--------------------------------

### TransGeo Paper Citation

Source: https://github.com/jeff-zilence/transgeo2022/blob/main/README.md

BibTeX entry for the TransGeo paper. Include this in your LaTeX documents when citing the work.

```bibtex
@inproceedings{zhu2022transgeo,
  title={TransGeo: Transformer Is All You Need for Cross-view Image Geo-localization},
  author={Zhu, Sijie and Shah, Mubarak and Chen, Chen},
  booktitle={Proceedings of the IEEE/CVF Conference on Computer Vision and Pattern Recognition},
  pages={1162--1171},
  year={2022}
}
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.