README.md

---
license: apache-2.0
pipeline_tag: image-to-3d
---

# QuerySplat: Decoupling Geometry and Appearance Representations in 3DGS Prediction

[Project Page](https://inspatio.github.io/querysplat) | [Paper](https://huggingface.co/papers/2608.01186) | [GitHub](https://github.com/inspatio/QuerySplat)

QuerySplat is a feed-forward 3D Gaussian Splatting (3DGS) framework driven by geometric priors and explicit appearance decoupling. Specifically, it uses a dual-branch query-based decoder where the geometry branch leverages a pretrained Vision Geometric Model for spatial understanding, while the appearance branch recovers high-frequency details through a dedicated pathway separated from geometric attribute regression.

## Installation

```bash
git clone https://github.com/inspatio/QuerySplat.git
cd QuerySplat

conda create -n querysplat python=3.12 -y
conda activate querysplat

# Tested configuration: PyTorch 2.11.0 + CUDA 12.8.
python -m pip install torch==2.11.0 torchvision==0.26.0 \
  --index-url https://download.pytorch.org/whl/cu128
python -m pip install --no-build-isolation -r requirements.txt
python -m pip install -U huggingface_hub
```

## Inference

Place any number of images from one scene in `--input_folder`. Run inference with Test-Time Optimization (TTO):

```bash
python -m scripts.infer \
  --config checkpoints/querysplat_vggto_1B_512_8192.yaml \
  --checkpoint checkpoints/querysplat_vggto_1B_512_8192.safetensors \
  --input_folder data/my_scene \
  --output_dir outputs/my_scene \
  --use_tto
```

Omit `--use_tto` to run the feed-forward model without test-time optimization.

## Citation

```bibtex
@article{li2026querysplat,
  title={QuerySplat: Decoupling Geometry and Appearance Representations in 3DGS Prediction},
  author={Li, Yinglong and Shen, Donghui and Zhang, Xiaoyu and Ye, Zhichao and Wu, Hongyu and Hao, Aimin and Zhang, Guofeng and Liu, Haomin},
  journal={arXiv preprint arXiv:2608.01186},
  year={2026}
}
```