MAG-VLAQ

MAG-VLAQ is a research codebase for multi-modal aerial-ground visual localization. The supported training path is the native PyTorch/Hydra stack:

• src/mag_vlaq/ as the importable Python package.
• Hydra/OmegaConf configuration.
• Plain PyTorch training loops.
• Native PyTorch DDP for 1/2/4/8 GPU training.

Legacy Lightning, argparse, and root-level model/data wrappers have been removed. Use the native PyTorch/Hydra entrypoints and mag_vlaq.* imports for new work.

Setup

Install the project in editable mode:

pip install -e .

For development tools:

pip install -e ".[dev]"

Optional dataset and retrieval dependencies are separated because they are environment-sensitive:

pip install -e ".[datasets,retrieval]"

On GPU servers, FAISS and PyTorch are often better installed through the local CUDA/conda stack instead of PyPI. Use the local cluster recipe if it already provides GPU FAISS or a specific H100-compatible PyTorch build.

External Model Dependencies

The current code expects external model sources:

• DINOv2 is loaded through torch.hub.load("facebookresearch/dinov2", ...).
• Utonia is imported as utonia.* by mag_vlaq.models.point_encoder.

Set UTONIA_ROOT or install Utonia into the active environment if it is not available from the repository-local demo/Utonia path. Local Utonia checkpoints can be configured through model.utonia.pretrained.

Training

Full KITTI360 native trainer:

export KITTI360_ROOT="$HOME/Datasets/cmvpr/kitti360/KITTI-360"

torchrun --standalone --nproc_per_node=1 train.py \
  experiment=kitti360_vlaq_odecq

Multi-GPU DDP examples:

torchrun --standalone --nproc_per_node=2 train.py \
  experiment=kitti360_vlaq_odecq train=ddp_2x

torchrun --standalone --nproc_per_node=4 train.py \
  experiment=kitti360_vlaq_odecq train=ddp_4x

torchrun --standalone --nproc_per_node=8 train.py \
  experiment=kitti360_vlaq_odecq train=ddp_8x_h100

Resume from a native checkpoint:

torchrun --standalone --nproc_per_node=1 train.py \
  experiment=kitti360_vlaq_odecq \
  train.resume=logs/<exp>/checkpoints/last.pt

Evaluation

python eval.py \
  experiment=kitti360_vlaq_odecq \
  output_dir=logs/kitti360_vlaq_odecq_eval \
  checkpoint=logs/kitti360_vlaq_odecq/checkpoints/last.pt

Project Layout

Core code lives under src/mag_vlaq/. Root-level legacy modules have been removed, so imports should come from mag_vlaq.data, mag_vlaq.models, mag_vlaq.losses, mag_vlaq.mining, mag_vlaq.retrieval, or mag_vlaq.engine.

Built With

• pytorch