Learning Scene-Level Signed Directional Distance Function with Ellipsoidal Priors and Neural Residuals

This repository contains the code for the paper "Learning Scene-Level Signed Directional Distance Function with Ellipsoidal Priors and Neural Residuals".

Setup

1. Install the dependencies:
   • Ubuntu 24.04:

     sudo apt install git build-essential cmake python3-full python3-pip pipenv libfmt-dev \
        libeigen3-dev libyaml-cpp-dev pybind11-dev libgl1 libglib2.0-dev
     # Also install CUDA
     # Tested: CUDA 12.6 with PyTorch 2.7.0

   • Arch Linux:

     sudo pacman -S git cuda make cmake python3 python-pipenv gcc14 fmt eigen yaml-cpp \
        pybind11 libglvnd libxrender

2. Clone the repository:

   git clone  https://github.com/ExistentialRobotics/neural-sddf.git
   cd neural-sddf

3. Create a virtual environment and install the package:
   • Note: when pip install . --verbose fails, it is better to remove the build directory before retrying.
   • pipenv:

     pipenv install --verbose
     pipenv shell
     pip install . --verbose
     # If /usr/bin/gcc is incompatible with the CUDA version, you can specify the compiler:
     # CC=/usr/bin/gcc-14 CXX=/usr/bin/g++-14 pip install . --verbose

   • conda:

     conda create -n neural-sddf python==3.12
     conda activate neural-sddf
     pip install . --verbose
     # If /usr/bin/gcc is incompatible with the CUDA version, you can specify the compiler:
     # CC=/usr/bin/gcc-14 CXX=/usr/bin/g++-14 pip install . --verbose
     
     # If you encounter an error related to `libstdc++.so.6`, you can fix it by running:
     rm $CONDA_PREFIX/lib/libstdc++.so
     rm $CONDA_PREFIX/lib/libstdc++.so.6
     ln -s /usr/lib/x86_64-linux-gnu/libstdc++.so $CONDA_PREFIX/lib/libstdc++.so
     ln -s /usr/lib/x86_64-linux-gnu/libstdc++.so.6 $CONDA_PREFIX/lib/libstdc++.so.6

4. Download the data: for the purpose of demonstration, we provide pre-generated datasets and trained models here. The following commands assume that the datasets and the models directories are placed in the root of the repository.

Train

python3 scripts/run.py --config config/replica-hotel-0-lidar.yaml

Test

python3 scripts/run.py --config <output_dir>/config.yaml \
    --test-model-file <output_dir>/model_XXX.pth
# Results will be saved in <output_dir>/test/epoch_XXX

Example output:

Ground Truth View	Ellipsoidal SDDF Prior	Neural SDDF

Demos

Single View Optimization

1. Run the script to optimize the view:

   python3 python/demo_view_opt.py --config data/view_opt/config.yaml \
       --model-path models/replica-office-0-lidar/model.pth
   # Results will be saved in `results/view_opt/<datetime>`

2. Run the script to visualize the result:

   python3 python/demo_view_opt.py --config results/view_opt/<datetime>/config.yaml \
       --play-dir results/view_opt/<datetime>

Trajectory Optimization

1. Run the script to optimize the trajectory:

   python3 python/demo_traj_opt.py --config data/traj_opt/config.yaml \
       --model-path models/gibson-allensville-lidar/model.pth
   # Results will be saved in `results/traj_opt/<datetime>`

2. Run the script to visualize the result:

   python3 python/demo_traj_opt.py --config results/traj_opt/<datetime>/config.yaml \
       --play-dir results/traj_opt/<datetime>

Single View Optimization	Trajectory Optimization

Citation

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

@misc{dai2025learningscenelevelsigneddirectional,
      title={Learning Scene-Level Signed Directional Distance Function with Ellipsoidal Priors and Neural Residuals}, 
      author={Zhirui Dai and Hojoon Shin and Yulun Tian and Ki Myung Brian Lee and Nikolay Atanasov},
      year={2025},
      eprint={2503.20066},
      archivePrefix={arXiv},
      primaryClass={cs.RO},
      url={https://arxiv.org/abs/2503.20066}, 
}