News

• [2025-12-31]: Release the initial version of codes, datasets, checkpoints.

TODO

• Release codes.
• Release datasets.
• Realese checkpoints.
• Add viewer.

Table of Contents

1. Installation
2. Dataset Preparation
3. Training
4. Mesh Extraction
5. Evaluation
6. Pretrained Models

Installation

Prerequisites

• CUDA 11.7 or higher
• Python 3.9
• PyTorch 1.13.1

Step-by-Step Installation

# Clone the repository with submodules
git clone --recursive https://github.com/xyzhang77/AtlasGS.git
cd AtlasGS

# Create conda environment
conda create -n atlasgs python=3.9 -y
conda activate atlasgs

# Install PyTorch
pip install torch==1.13.1+cu117 torchvision==0.14.1+cu117 torchaudio==0.13.1 --extra-index-url https://download.pytorch.org/whl/cu117

# Install dependencies
pip install -r requirements.txt

# Install custom rasterization module
pip install submodules/diff-surfel-rasterization --no-build-isolation

# Install torch-scatter
pip install torch-scatter -f https://data.pyg.org/whl/torch-1.13.1+cu117.html --no-build-isolation

Dataset Preparation

For detailed dataset preprocessing instructions, please refer to DATASET_PREPROCESSING.md.

Quick Start

Option 1: Download Preprocessed Datasets

We provide preprocessed datasets for immediate use:

• ScanNet: scene0050_00, scene0084_00, scene0580_00, scene0616_00
• ScanNet++: 8b5caf3398, b20a261fdf, f34d532901, f6659a3107
• Replica: office0-3, room0-2

Option 2: Process Custom Datasets

For processing custom datasets (ScanNet, Replica, ScanNet++, COLMAP) and generating geometry priors (depth, normals, semantics), see the complete guide in DATASET_PREPROCESSING.md.

Basic Dataset Structure

After processing, each dataset should have the following structure:

data/
├── scene_name/
│   ├── images/
│   │   ├── 000000.png
│   │   ├── 000001.png
│   │   └── ...
│   ├── sparse/
│   │   ├── cameras.bin
│   │   ├── images.bin
│   │   └── points3D.bin
│   ├── depths/ (optional)
│   ├── normals/ (optional)
│   └── semantics/ (optional)

Training Examples

ScanNet Training

# Train on ScanNet scene
python train.py \
    -s data/scannet/scene0050_00 \
    -m output/scene0050_00 \

Replica Training

# Train on Replica scene
python train.py \
    -s data/replica/office0 \
    -m output/office0 \

Mesh Extraction

python render.py -m <model_path> --skip_train --skip_test

Rendering Images

# Render training views
python render.py -m output/scene0050_00

# Render test views only
python render.py -m output/scene0050_00 --skip_train

# Render interpolated camera trajectory
python render.py -m output/scene0050_00 --render_path

Evaluation

Download ground truth meshes from google drive.

ScanNet Evaluation

python -m evaluation.eval_scannet \
    --scene scene0050_00 \
    --mesh_path output/scene0050_00/train/ours_40000/fuse_post.ply

ScanNet++ Evaluation

python -m evaluation.eval_scannetpp \
    --scene <scene_name> \
    --mesh_path <path_to_extracted_mesh>

Replica Evaluation

python -m evaluation.eval_replica \
    --scene office0 \
    --mesh_path output/office0/train/ours_25000/fuse_post.ply

Evaluation Metrics

The evaluation script computes the following metrics:

• Accuracy (Acc): Mean distance from predicted to ground truth
• Completeness (Comp): Mean distance from ground truth to predicted
• Precision: Percentage of points within threshold
• Recall: Percentage of ground truth points within threshold
• F-score: Harmonic mean of precision and recall

The evaluation also generates:

• Colored point clouds showing precision/recall errors
• Precision-Recall curves
• Detailed metrics saved as JSON

Batch Evaluation

For multiple scenes, you can use the provided scripts:

# Evaluate all ScanNet scenes
python scripts/train_eval_scannet.py

# Evaluate all Replica scenes
python scripts/train_eval_replica.py

# Evaluate all ScanNet++ scenes
python scripts/train_eval_scannetpp.py

Pretrained Models

We provide pretrained models for quick testing and evaluation without training from scratch.

Available Models

• ScanNet: scene0050_00, scene0084_00, scene0580_00, scene0616_00
• ScanNet++: 8b5caf3398, b20a261fdf, f34d532901, f6659a3107
• Replica: office0-3, room0-2

Usage

# Use for rendering
python render.py -m path/to/pretrained/model

# Use for mesh extraction
python render.py -m path/to/pretrained/model --skip_train --skip_test

Acknowledgments

We acknowledge the following inspiring prior work:

• 2DGS: 2D Gaussian Splatting for Geometrically Accurate Radiance Fields
• Scaffold-GS: Structured 3D Gaussians for View-Adaptive Rendering
• Neural 3D Scene Reconstruction with the Manhattan-world Assumption

Citation

If you use this code in your research, please cite:

@article{zhang2026atlasgs,
  title={AtlasGS: Atlanta-world Guided Surface Reconstruction with Implicit Structured Gaussians},
  author={Zhang, Xiyu and Bao, Chong and Chen, Yipeng and Zhai, Hongjia and Dong, Yitong and Bao, Hujun and Cui, Zhaopeng and Zhang, Guofeng},
  journal={Advances in Neural Information Processing Systems},
  volume={38},
  pages={15556--15580},
  year={2026}
}

---

For any questions or issues, please open an issue on the GitHub repository or contact the authors with the email.