This is an official implementation of the paper "ActiveGAMER: Active GAussian Mapping through Efficient Rendering".
Liyan Chen*†1,2,
Huangying Zhan*†‡1,
Kevin Chen1,
Xiangyu Xu1,
Qingan Yan1,
Changjiang Cai1,
Yi Xu1
1 OPPO US Research Center, 2 Stevens Institute of Technology
* Co-first authors with equal contribution
† Work done as an intern at OPPO US Research Center
‡ Corresponding author
- 📁 Repo Structure
- 🛠️ Installation
- 💿 Dataset Preparation
- 🏃♂️ Running ActiveGAMER
- 🔎 Evaluation
- 📜 License
- 🤝 Acknowledgement
- 📖 Citation
# 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}
│ │ └── ...
│ │ └── ...
│ │ └── ...
# 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.
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
Follow the steps to install the conda environment
# Build conda environment
bash scripts/installation/conda_env/build.sh
# Activate conda env
source activate activegamer
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.
- ReplicaSLAM: a SLAM dataset with predefined trajectory. Used for passive mapping experiement, and pose initialization for the first frame.
- 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.
- 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
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 script:
python download_mp.py -o data/MP3D --task_data habitat
# Unzip data
cd data/MP3D/v1/
unzip mp3d_habitat.zip
rm mp3d_habitat.zip
cd ${ROOT}
Include new/modified SplaTAM source code and configurations to SplaTAM directory.
bash scripts/activegamer/update_splatam.sh
Here we provide the script to run the full system described in the paper. This script also includes the upcoming evaluation process.
# Run Replica
bash scripts/activegamer/run_replica.sh {SceneName/all} {NUM_TRIAL} {EXP_NAME} {ENABLE_VIS}
# Run MP3D
bash scripts/activegamer/run_mp3d.sh {SceneName/all} {NUM_TRIAL} {EXP_NAME} {ENABLE_VIS}
# examples
bash scripts/activegamer/run_replica.sh office0 1 ActiveGAMER 1
bash scripts/activegamer/run_mp3d.sh gZ6f7yhEvPG 1 ActiveGAMER 0
bash scripts/activegamer/run_replica.sh all 5 ActiveGAMER 0
We evaluate the reconstruction using the following metrics with a threshold of 5cm:
- Accuracy (cm)
- Completion (cm)
- Completion ratio (%)
We also compute the mean absolute distance, MAD (cm), between the estimated SDF distance on all vertices from the ground truth mesh.
# Evaluate Replica result
bash scripts/evaluation/eval_replica_activegamer_recon.sh {SceneName/all} {TrialIndex} {EXP_NAME}
bash scripts/evaluation/eval_mp3d_activegamer_recon.sh {SceneName/all} {TrialIndex} {EXP_NAME}
# Examples
bash scripts/evaluation/eval_replica_activegamer_recon.sh office0 0 2000
bash scripts/evaluation/eval_mp3d_activegamer_recon.sh gZ6f7yhEvPG 0 5000
ActiveGAMER is licensed under MIT licence. For the third parties, please refer to their license.
- HabitatSim: MIT License
- SplaTAM: BSD-3-Clause License
The following files are adapted from third-party sources and modified. Their original licenses still apply:
utils/c2e_utils.py
Based on py360convert/utils.py — MIT Licensesrc/evaluation/eval_recon.py
We also gratefully acknowledge projects whose ideas inspired this work but whose source code is not included here, e.g. gradslam, etc.
@article{chen2025activegamer,
title={ActiveGAMER: Active GAussian Mapping through Efficient Rendering},
author={Chen, Liyan and Zhan, Huangying and Chen, Kevin and Xu, Xiangyu and Yan, Qingan and Cai, Changjiang and Xu, Yi},
journal={arXiv preprint arXiv:2501.06897},
year={2025}
}