ActiveGAMER

Active GAussian Mapping through Efficient Rendering (CVPR - 2025)

<a href='https://oppo-us-research.github.io/ActiveGAMER-website/'><img src='https://img.shields.io/badge/Project-Page-Green'></a> <a href='https://arxiv.org/abs/2501.06897'><img src='https://img.shields.io/badge/Paper-Arxiv-red'></a> <a href='https://github.com/oppo-us-research/ActiveGAMER-website/blob/main/static/images/cvpr25_poster_activegamer.png'><img src='assets/poster_badge.png' width=78 height=21></a>

This is an official implementation of the paper "ActiveGAMER: Active GAussian Mapping through Efficient Rendering".

Liyan Chen^*†1,2, Huangying Zhan^*†‡1, Kevin Chen¹, Xiangyu Xu¹, <br> Qingan Yan¹, Changjiang Cai¹, Yi Xu¹

¹ OPPO US Research Center, ² Stevens Institute of Technology

^* Co-first authors with equal contribution </br> ^† Work done as an intern at OPPO US Research Center </br> ^‡ Corresponding author </br>

Table of Contents

• 📁   Repo Structure
• 🛠️   Installation
• 💿   Dataset Preparation
• 🏃‍♂️   Running ActiveGAMER
• 🔎   Evaluation
• 📜   License
• 🤝   Acknowledgement
• 📖   Citation

<h2 id="repo-structure"> 📁 Repo Structure </h2>

# Main directory
├── ActiveGAMER (ROOT)
│   ├── assets                                      # README assets
│   ├── configs                                     # experiment configs
│   ├── data                                        # dataset
│   │   └── MP3D                                    # Matterport3D for Habitat data
│   │   └── ReplicaSLAM                             # Replica SLAM Dataset
│   │   └── replica_v1                              # Replica Dataset v1
│   ├── envs                                        # environment installation 
│   ├── results                                     # experiment results
│   ├── scripts                                     # scripts
│   │   └── activegamer                             # running ActiveGAMER scripts
│   │   └── data                                    # data related scripts
│   │   └── evaluation                              # evaluation related scripts
│   │   └── installation                            # installation related scripts
│   ├── src                                         # source code
│   │   └── data                                    # data code
│   │   └── evaluation                              # evaluation code
│   │   └── layers                                  # pytorch layers
│   │   └── main                                    # main framework code
│   │   └── planer                                  # planer code
│   │   └── simulator                               # simulator code
│   │   └── slam                                    # SLAM code
│   │   └── utils                                   # utility code
│   │   └── visualization                           # visualization code
│   ├── third_party                                 # third_party


# Data structure
├── data                                            # dataset dir
│   ├── MP3D                                        # Matterport3D data
│   │   └── v1
│   │       └── tasks
│   │           └── mp3d_habitat
│   │               ├── 1LXtFkjw3qL
│   │               └── ...
│   ├── replica_v1                                  # Replica-Dataset
│   │   └── apartment_0
│   │       └── habitat
│   │           └── replicaSDK_stage.stage_config.json
│   │   └── ...
│   ├── Replica                                     # Replica SLAM Dataset
│   │   └── office_0
│   │   └── ...

# Configuration structure
├── configs                                         # configuration dir
│   ├── default.py                                  # Default overall configuration
│   ├── MP3D                                        # Matterport3D 
│   │   └── ActiveGAMER                             # ActiveGAMER default configuration for MP3D
│   │       └── mp3d_splatam_s.yaml                 # SplaTAM-small default configuration for MP3D
│   │       └── mp3d_splatam.yaml                   # SplaTAM default configuration for MP3D
│   │   └── {SCENE}
│   │       └── {EXP}.py                            # experiment-specific overall configuraiton, inherit from default.py
│   │       └── habitat.py                          # scene-specific HabitatSim configuration
│   │   └── ...
│   ├── Replica                                     # Replica
│   │   └── ...

NOTE: default.py and {EXP}.py have the highest priority that can override configurations in other config files (e.g. *.yaml, habitat.py)

# Result structure
├── results                                         # result dir
│   ├── Replica                                     # Replica result
│   │   └── office_0
│   │       └── {EXPERIMENT_SETUP}
│   │           └── run_{COUNT}
│   │               └── eval_3d                     # 3D Reconstruction evaluation results
│   │                   └── {STAGE}
│   │                       └── eval_3d_result.txt  # result summary
│   │                       └── pt_err_*.ply        # 3D error visualization
│   │                       └── rec_pc_tri.ply      # reconstructed point cloud extracted from 3DGS
│   │               └── logger                      # SplaTAM event logging
│   │               └── splatam
│   │                   └── eval                    # Training set evaluation
│   │                   └── eval_{STAGE}            # Novel View Synthesis evaluation
│   │                       └── plots               # NVS qualitative results
│   │                       └── *.txt               # NVS quantitative results
│   │                   └── {STAGE}                 # 3DGS Parameters
│   │                   └── config.py               # splatam configuration
│   │               └── main_cfg.json               # main configuration
│   ├── MP3D                                        # Matterport3D result
│   │   └── GdvgFV5R1Z5
│   │       └── {EXPERIMENT_SETUP}
│   │           └── run_{COUNT}
│   │               └── ...
│   │   └── ...
│   │   └── ...

<h2 id="installation"> 🛠️ Installation </h2>

Install ActiveGAMER

# Clone the repo with the required third parties.
git clone --recursive https://github.com/oppo-us-research/ActiveGAMER.git

# We assume ROOT as the project directory.
cd ActiveGAMER
ROOT=${PWD}

In this repo, we provide two types of environement installations: Docker and Anaconda.

Users can optionally install one of them. The installation process includes:

• installation of Habitat-Sim, where we install our updated Habitat-Sim, where the geometry compilation is updated.

• installation of SplaTAM, which is used as ActiveGAMER's mapping backbone

• installation of other packages required to run ActiveGAMER.

[Optional 1] Docker Environment

Follow the steps to install the Docker environment:

# Build Docker image
bash scripts/installation/docker_env/build.sh

# Run Docker container. Update the mount volume accordingly.
bash scripts/installation/docker_env/run.sh

# Activate conda env in Docker Env
conda activate activegamer

[Optional 2] Conda Environment

Follow the steps to install the conda environment

# Build conda environment
bash scripts/installation/conda_env/build.sh

# Activate conda env
source activate activegamer

<h2 id="dataset-preparation"> 💿 Dataset Preparation </h2>

Replica Data

Follow the steps to download Replica Dataset.

# Download Replica data and save as data/replica_v1.
# This process can take a while.
bash scripts/data/replica_download.sh data/replica_v1

# Once the donwload is completed, create modified Habitat Simulator configs that adjust the coordinate system direction.
# P.S. we adjust the config so the coordinates matches with the mesh coordinates.
bash scripts/data/replica_update.sh data/replica_v1

We use three versions of Replica data for different purposes.

1. ReplicaSLAM: a SLAM dataset with predefined trajectory. Used for passive mapping experiement, and pose initialization for the first frame.
2. ReplicaSLAM-Habitat: Use same trajectory in (1) but using HabitatSim to re-generate the RGBD data, as (1)'s generated RGBD does not match with HabitatSim's simulation data. e.g. different lighting configuration.
3. ReplicaNVS: Novel View Synthesis evaluation data.

# (1) Download ReplicaSLAM Data and save as data/Replica
bash scripts/data/replica_slam_download.sh

# (2) Generate (1) using HabitatSim
bash scripts/data/generate_replica_habitat.sh all

# (3) Generate Replica NVS data
bash scripts/data/generate_replica_nvs.sh all

Matterport3D

To download Matterport3D dataset, please refer to the instruction in Matterport3D.

The download script is not included here as there is a Term of Use agreement for using Matterport3D data.

However, our method does not require the full Matterport3D dataset. Users can download the data related to the task habitat only.

# Example use of the Matterport3D download sc