CamFlow: Estimating 2D Camera Motion with Hybrid Motion Basis

CamFlow presents a novel approach for 2D camera motion estimation using hybrid motion basis decomposition. Our method achieves state-of-the-art performance on camera motion estimation tasks while maintaining computational efficiency.

---

🚀 Quick Start

📦 Data Acquisition

Option A: Minimal Download (130MB) — Essential files only

python download_data.py --minimal

Dataset Structure:

data/CamFlow-ICCV25/
├── basis_24.pt      # Motion basis (35MB)
├── ckpt.pth         # Model weights (93MB) 
├── params.json      # Model configuration
└── test_imgs/       # Test image pairs
    ├── img1.png
    └── img2.png

Option B: Complete Dataset (5.5GB) — Full benchmark suite

python download_data.py

Additional Contents: comparison_methods.zip (2.56GB), GHOF-Cam.npy (2.8GB)

Option C: Hugging Face CLI — Alternative download method

pip install huggingface_hub
huggingface-cli download Lhaippp/CamFlow-ICCV25 --repo-type dataset --local-dir data

Data Source: 🤗 Lhaippp/CamFlow-ICCV25

⚙️ Environment Setup

# Automated setup (recommended)
python setup_environment.py && source camflow_env/bin/activate

Manual Setup — Advanced users

# Create virtual environment
python -m venv camflow_env && source camflow_env/bin/activate

# Install dependencies
pip install -r requirements.txt

# Optional: GPU-accelerated PyTorch
pip install torch torchvision --index-url https://download.pytorch.org/whl/cu118

🎯 Inference

Basic Usage:

python blind_inference.py  # Uses test images from data/test_imgs/

Advanced Usage:

# Custom image paths
python blind_inference.py --image_paths /path/to/img1.png /path/to/img2.png

# Custom model directory  
python blind_inference.py --model_path custom.pth --imgs_dir custom_images/

---

📊 Evaluation & Benchmarking

Model Evaluation

# Standard evaluation
python eval_main.py --model_dir data/CamFlow-ICCV25 --restore_file data/CamFlow-ICCV25/ckpt.pth

# With Image Quality Assessment metrics
python eval_main.py --model_dir data/CamFlow-ICCV25 --restore_file data/CamFlow-ICCV25/ckpt.pth --enable_iqa

Comparative Analysis

Generate visual comparisons with baseline methods:

python create_comparison_gif.py --folder comparison_methods

Note: Image arrangements vary by method:

• Identity method: [img1, img2]
• Other methods: [img2_warped, img1_warped]

---

📚 Citation

If you find CamFlow useful in your research, please consider citing:

@article{li2025estimating,
  title={Estimating 2D Camera Motion with Hybrid Motion Basis},
  author={Li, Haipeng and Zhou, Tianhao and Yang, Zhanglei and Wu, Yi and Chen, Yan and Mao, Zijing and Cheng, Shen and Zeng, Bing and Liu, Shuaicheng},
  journal={arXiv preprint arXiv:2507.22480},
  year={2025}
}

---

🙏 Acknowledgements

We gratefully acknowledge the following contributions that made this work possible:

• GyroFlowPlus for providing the foundational dataset infrastructure
• DeepHomography for pioneering deep homography estimation and providing essential training data
• BasesHomo for their elegant and effective motion basis decomposition ideas
• HomoGAN and DMHomo for the 8-basis foundation models and data augmentation strategies

Special thanks to our co-authors for their invaluable contributions.