EAGLE-ReID

Official code release for EAGLE-ReID: Strategic Alignment and Delta Consistency for Extreme Far-Distance Aerial-Ground Re-Identification, WACV 2026 VReID-XFD Workshop.

EAGLE-ReID is a competition-oriented extension of VSLA-CLIP for the DetReIDX extreme far-distance aerial-ground video ReID benchmark. The method keeps the CLIP/VSLA-CLIP adapter backbone and focuses on the training dynamics that mattered most in the challenge:

• Geometry-Aware Sampler (GAS): constructs 1 Ground + K Aerial groups per identity so every mini-batch contains cross-view supervision.
• View-Manifold Delta (VMD): encourages consistent ground-to-aerial feature transformations instead of forcing rigid feature collapse.
• CLIP image-text alignment: retains the original VSLA-CLIP two-stage visual-language training pipeline.

The system ranked 3rd place in the WACV 2026 VReID-XFD challenge and reached 29.00% official test mAP.

Repository Layout

configs/adapter/eagle_reid.yml         Main EAGLE-ReID training config
configs/adapter/vit_adapter.yml        Backward-compatible alias of the main config
datasets/make_video_dataloader.py      DetReIDX dataloader with view labeling + GAS
datasets/sampler.py                    RandomPidOneToManySampler implementation
processor/processor_videoreid_stage2.py Stage-2 VMD / delta consistency losses
model/                                CLIP/VSLA-CLIP adapter model
evaluate_all_cases.py                 Official-style submission ranking generation
run_tsne_analysis.py                  Diagnostic t-SNE visualizations
tools/build_proxy_val_split.py         Optional ID-held-out proxy validation split
docs/assets/tsne/                     Paper/diagnostic t-SNE figures

Environment

The original experiments used Python 3.8, PyTorch 1.8, CUDA 10.2, and NVIDIA A100 GPUs.

conda create -n eagle-reid python=3.8
conda activate eagle-reid
conda install pytorch==1.8.0 torchvision==0.9.0 torchaudio==0.8.0 cudatoolkit=10.2 -c pytorch
pip install -r requirements.txt

On first run, CLIP weights are downloaded by model/clip/clip.py unless they already exist in the local cache.

Dataset

Download DetReIDX from the challenge organizers and place it outside the repository, for example:

/path/to/DetReIDX/

Then update:

DATASETS:
  NAMES: ('detreidx')
  ROOT_DIR: ('/path/to/DetReIDX')

See docs/DATASET.md for the expected layout and notes on view labeling.

To create a local proxy validation split from the official training set:

python tools/build_proxy_val_split.py \
  --src-root /path/to/DetReIDX \
  --out-root /path/to/DetReIDX_proxy_val_seed2026 \
  --seed 2026 \
  --val-ratio 0.2

Training

CUDA_VISIBLE_DEVICES=0 python train_reidadapter.py \
  --config_file configs/adapter/eagle_reid.yml

To skip stage 1 and initialize from a stage-1 checkpoint:

CUDA_VISIBLE_DEVICES=0 python train_reidadapter.py \
  --config_file configs/adapter/eagle_reid.yml \
  --stage1weight /path/to/ViT-B-16_stage1_120.pth

The main config writes checkpoints to OUTPUT_DIR. Checkpoints, logs, TensorBoard files, generated rankings, and local datasets are ignored by git.

Paper-component mapping:

• datasets/make_video_dataloader.py assigns Ground/Aerial labels and uses the GAS sampler in stage 2.
• datasets/sampler.py implements the 1 Ground + K Aerial mini-batch grouping.
• processor/processor_videoreid_stage2.py adds VMD losses: ground-to-aerial delta consistency and aerial intra-PID consistency.

Evaluation

Single-query/gallery evaluation:

CUDA_VISIBLE_DEVICES=0 python test.py \
  --config_file configs/adapter/eagle_reid.yml \
  TEST.WEIGHT /path/to/ViT-B-16_120.pth

Challenge submission ranking generation:

CUDA_VISIBLE_DEVICES=0 python evaluate_all_cases.py \
  --config_file configs/adapter/eagle_reid.yml \
  --model_path /path/to/ViT-B-16_120.pth

This produces evaluation_rankings_all_galleries.csv under the configured output directory.

Diagnostics

The t-SNE analysis used in the paper can be reproduced with:

CUDA_VISIBLE_DEVICES=0 python run_tsne_analysis.py \
  --config_file configs/adapter/eagle_reid.yml \
  --weight /path/to/ViT-B-16_120.pth \
  --output_dir docs/assets/tsne

Reference figures are included in docs/assets/tsne/.

Citation

@inproceedings{kang2026eagle,
  title={EAGLE-ReID: Strategic Alignment and Delta Consistency for Extreme Far-Distance Aerial-Ground Re-Identification},
  author={Kang, Cheng-Jun and Jiang, Jin-Hui and Lin, Yu-Fan and Hsu, Chih-Chung},
  booktitle={Proceedings of the IEEE/CVF Winter Conference on Applications of Computer Vision Workshops},
  year={2026}
}

Acknowledgements

This codebase builds on VSLA-CLIP, CLIP-ReID, TransReID, OpenAI CLIP, and CoOp. We thank the VReID-XFD / DetReIDX organizers for the benchmark and evaluation protocol.