NeRFICG -->

May 28, 2026 · View on GitHub

A flexible PyTorch framework for simple and efficient implementation of radiance field and view synthesis methods, including a GUI for interactive rendering.

Getting Started

Requirements: Our framework requires Linux (preferred) or Windows as well as a reasonably recent NVIDIA GPU.

Install a CUDA SDK (we recommend CUDA Toolkit 12.8) and a compatible C++ compiler. Depending on your system there are some additional steps required to make sure everything is set up correctly.
- Linux: Make sure the CUDA SDK is correctly installed and added to your environment variables. On Ubuntu, we usually add the following lines to the top of our .bashrc file for CUDA 12.8:
```
export PATH="/usr/local/cuda-12.8/bin:$PATH"
export LD_LIBRARY_PATH="/usr/local/cuda-12.8/lib64:$LD_LIBRARY_PATH"
export CUDA_PATH="/usr/local/cuda-12.8/"
```
  We recommend gcc as the C++ compiler. Make sure to check the version requirements of your CUDA SDK.
- Windows: Make sure the corresponding environment variables are set. This should typically be done automatically by the CUDA installer, but make sure the CUDA_PATH and CUDA_HOME variables are set and point to the correct installation directory. We recommend Visual Studio Community 2022 as the C++ compiler. Make sure to install the Desktop development with C++ workload as well as the recommended MSVC build tools.

This repository uses submodules, clone using one of the following options:

# HTTPS
git clone https://github.com/nerficg-project/nerficg.git --recursive ./nerficg && cd nerficg

# SSH
git clone git@github.com:nerficg-project/nerficg.git --recursive ./nerficg && cd nerficg

Set up a Conda environment that contains all dependencies using:
```
SET DISTUTILS_USE_SDK=1  # Windows only
conda env create -f ./environments/py311_cu128.yaml
conda activate nerficg
```
Depending on your system and goals, you might want to install a different environment. We provide multiple options in the environments directory. For example, if you plan on using our COLMAP script (see below), you would want to use an environment file with the _with_colmap suffix.
To install all additional dependencies for a specific method, run:
```
python ./scripts/install.py -m <METHOD_NAME>
```
or use
```
python ./scripts/install.py -e <PATH_TO_EXTENSION>
```
to (re-)install a specific extension or one of the third-party modules in src/Thirdparty/.
- Windows: If the script fails to locate the compiler, run it inside of a x64 Native Tools Command Prompt for VS 20XX and set the DISTUTILS_USE_SDK environment variable:
```
set DISTUTILS_USE_SDK=1
```
  Also, because of legacy filename limitations in Windows, the installation may fail depending on the location of the repository on your system. If you get errors about filenames, files not being found, or path issues, try moving the repository directory to a shorter path (e.g. C:\nerficg) and try again.
[optional] To use our training visualizations with Weights & Biases, run the following command and enter your account identifier:
```
wandb login
```

Creating a Configuration File

To create a configuration file for training, run

python ./scripts/create_config.py -m <METHOD_NAME> -d <DATASET_TYPE> -o <CONFIG_NAME>

where <METHOD_NAME> and <DATASET_TYPE> match one of the items in the src/Methods and src/Datasets directories, respectively. The resulting configuration file <CONFIG_NAME>.yaml will be available in the configs directory and can be customized as needed. To create a directory of configuration files for all scenes of a dataset, use the -a flag. This requires the full dataset to be available in the dataset directory.

Training a New Model

To train a new model from a configuration file, run:

python ./scripts/train.py -c configs/<CONFIG_NAME>.yaml

The resulting images and model checkpoints will be saved to the output directory.

To train multiple models from a directory or list of configuration files, use the scripts/sequential_train.py script with the -d or -c flag respectively.

Training on Custom Image Sequences

If you want to train on a custom image sequence, create a new directory with an images subdirectory containing all training images. Then you can prepare the image sequence using the provided COLMAP script, including various preprocessing options like monocular depth estimation, image segmentation and optical flow. Run

python ./scripts/colmap.py -h

to see all available flags and options.

After calibration, the custom dataset can be loaded by setting Colmap as GLOBAL.DATASET_TYPE in the config file and entering the correct directory path in the config file under DATASET.PATH.

Inference and Evaluation

We provide multiple scripts for easy model inference and performance evaluation after training. Use the scripts/inference.py script to render output images for individual subsets (train/test/eval) or custom camera trajectories defined in src/Visual/Trajectories using the -s option. Additional rendering performance benchmarking and metric calculation is available using the -b and -m flags respectively .

The scripts/generate_tables.py script further enables consistent metric calculation over multiple pre-generated output image directories (e.g. to compare multiple methods against GT), and automatically generates LaTeX code for tables containing the resulting values. Use -h to see the available options for all scripts.

Graphical User Interface

To inspect a pretrained model in our GUI, make sure the GUI submodule is initialized, run

python ./scripts/gui.py

and select the generated output directory.

Some methods support live GUI interaction during optimization. To enable live GUI support, activate the TRAINING.GUI.ACTIVATE flag in your config file.

Frequently Asked Questions (FAQ)

Q: What coordinate system do the framework and GUI use internally?

A: Framework and GUI use the same right-handed coordinate system for world and camera space in all calculations. The convention is the same as in, e.g., COLMAP, meaning x is right, y is down, and z is forward.

Q: Can I use the modules in the src/CudaUtils directory outside of the NeRFICG framework?

A: Yes! For example, to install the MortonEncoding module via pip, simply run

pip install git+https://github.com/nerficg-project/nerficg/#subdirectory=src/CudaUtils/MortonEncoding --no-build-isolation

Q: Commercial use?

A: Our base framework is licensed under the MIT license, which permits commercial use. However, some optional extensions and third-party modules use licenses that prohibit commercial use:

src/Optim/knn_utils.py defaults to using code licensed under the non-commercial Gaussian-Splatting License. We provide a slightly slower but commercially viable and more generic implementation that can be enabled by setting _ALLOW_PROPRIETARY_LICENSED_CODE = False.
The GaussianSplatting method requires the diff-gaussian-rasterization module, which is licenced under the non-commercial Gaussian-Splatting License. We recommend the NeRFICG-based Faster-GS implementation as a commercially viable alternative.

Acknowledgments

We started working on this project in 2021. Over the years many projects have inspired and helped us to develop this framework. Apart from any reference you might find in our source code, we would specifically like to thank all authors of the following projects for their great work:

License and Citation

This framework is licensed under the MIT license (see LICENSE).

If you use it in your research projects, please consider a citation:

@software{nerficg,
	author = {Kappel, Moritz and Hahlbohm, Florian and Scholz, Timon},
	license = {MIT},
	month = {2},
	title = {NeRFICG},
	url = {https://github.com/nerficg-project},
	version = {2.0},
	year = {2026}
}