AirV2X‑Perception

Official implementation of
“AirV2X: Unified Air–Ground/Vehicle‑to‑Everything Collaboration for Perception”

---

🌐 Dataset

Download AirV2X‑Perception from Hugging Face and extract it to any location:

mkdir dataset
cd dataset # Use another directory to avoid naming conflict
conda install -c conda-forge git-lfs
git lfs install --skip-smudge
git clone https://huggingface.co/datasets/xiangbog/AirV2X-Perception
cd AirV2X-Perception
git lfs pull
# git lfs pull --include "path/to/folder"   # If you would like to download only partial of the dataset

We also provide a mini batch for quick testing and debugging.

---

🔧 Installation

Detailed instructions and environment specifications are in doc/INSTALL.md.

---

🚀 Model Training

Single‑GPU

python opencood/tools/train.py \
    -y /path/to/config_file.yaml

Example: train Where2Comm (LiDAR‑only)

python opencood/tools/train.py \
    -y opencood/hypes_yaml/airv2x/lidar/det/airv2x_intermediate_where2com.yaml

Tip
Some models such as V2X‑ViT and CoBEVT consume a large amount of VRAM.
Enable mixed‑precision with --amp if you encounter OOM, but watch out for NaN/Inf instability.

python opencood/tools/train.py \ 
    -y opencood/hypes_yaml/airv2x/lidar/det/airv2x_intermediate_v2xvit.yaml       
    --amp

Multi‑GPU (DDP)

CUDA_VISIBLE_DEVICES=0,1,2,3 torchrun \
    --standalone --nproc_per_node=4 \     
    opencood/tools/train.py \
        -y /path/to/config_file.yaml

Example: LiDAR‑only Where2Comm with 8 GPUs

CUDA_VISIBLE_DEVICES=0,1,2,3,4,5,6,7 torchrun \       
    --standalone\
    --nproc_per_node=8 \
    opencood/tools/train.py \
        -y opencood/hypes_yaml/airv2x/lidar/det/airv2x_intermediate_where2com.yaml

Multi‑Stage Models (HEAL, STAMP)

These models were trained on 2 nodes × 1 GPU (batch size 1).
If you change the number of GPUs or batch size, adjust the learning rate accordingly.

---

📝 Evaluation

python opencood/tools/inference_multi_scenario.py \ 
    --model_dir opencood/logs/airv2x_intermediate_where2comm/default__2025_07_10_09_17_28 \
    --eval_best_epoch \
    --save_vis

---

🔍 Visualization

tensorboard --logdir opencood/logs --port 10000 --bind_all

---

📄 Citation

@article{gao2025airv2x,
  title   = {AirV2X: Unified Air--Ground/Vehicle-to-Everything Collaboration for Perception},
  author  = {Gao, Xiangbo and Tu, Zhengzhong and others},
  journal = {arXiv preprint arXiv:2506.19283},
  year    = {2025}
}

---

We will continuously update this repository with code, checkpoints, and documentation.
Feel free to open issues or pull requests — contributions are welcome! 🚀