cifasis / basalt-xr

Basalt for Monado

This is a fork of Basalt improved for tracking XR devices with Monado. Many thanks to the Basalt authors.

Installation

• Ubuntu 22.04: Download latest .deb and install with

  sudo apt install -y ./basalt-monado-ubuntu-22.04-haswell-amd64.deb

• From source (minimal)

  git clone --recursive https://gitlab.freedesktop.org/mateosss/basalt.git
  cd basalt && ./scripts/install_deps.sh
  cmake -B build -G Ninja -DCMAKE_BUILD_TYPE=Release -DBASALT_BUILD_SHARED_LIBRARY_ONLY=on
  sudo cmake --build build --target install

• From source (with extra binaries and debug symbols)

  git clone --recursive https://gitlab.freedesktop.org/mateosss/basalt.git
  cd basalt && ./scripts/install_deps.sh
  cmake -B build -G Ninja -DCMAKE_BUILD_TYPE=RelWithDebInfo -DBASALT_INSTANTIATIONS_DOUBLE=off -DBUILD_TESTS=off
  sudo cmake --build build --target install

Usage

If you want to run OpenXR application with Monado, you need to set the environment variable VIT_SYSTEM_LIBRARY_PATH to the path of the basalt library.

By default, Monado will try to load the library from /usr/lib/libbasalt.so if the environment variable is not set.

If you want to test whether everything is working you can download a short dataset with EuRoC (ASL) format format like MIO09_short_1_updown from the Monado SLAM datasets:

wget https://huggingface.co/datasets/collabora/monado-slam-datasets/resolve/main/M_monado_datasets/MI_valve_index/MIO_others/MIO09_short_1_updown.zip
unzip -d MIO09_short_1_updown MIO09_short_1_updown.zip

• Try it standalone with a dataset (requires extra binaries)

  basalt_vio --show-gui 1 --dataset-path MIO09_short_1_updown/ --dataset-type euroc --cam-calib /usr/share/basalt/msdmi_calib.json --config-path /usr/share/basalt/msdmi_config.json

• Use a RealSense camera without Monado (requires extra binaries) You'll need to calibrate your camera if you want the best results but meanwhile you can try with these calibration files instead.

  • RealSense D455 (and maybe also D435)

    basalt_rs_t265_vio --is-d455 --cam-calib /usr/share/basalt/d455_calib.json --config-path /usr/share/basalt/msdmi_config.json

  • Realsense T265: Get t265_calib.json from this issue and run

    basalt_rs_t265_vio --cam-calib t265_calib.json --config-path /usr/share/basalt/msdmi_config.json

• Try it through monado-cli with a dataset

  monado-cli slambatch MIO09_short_1_updown/ /usr/share/basalt/msdmi.toml results

• Try it with monado, a dataset, and an OpenXR app

  # Run monado-service with a fake "euroc device" driver
  export EUROC_PATH=MIO09_short_1_updown/ # dataset path
  export EUROC_HMD=false # false for controller tracking
  export EUROC_PLAY_FROM_START=true # produce samples right away
  export SLAM_CONFIG=/usr/share/basalt/msdmi.toml # includes calibration
  export SLAM_SUBMIT_FROM_START=true # consume samples right away
  export XRT_DEBUG_GUI=1 # enable monado debug ui
  monado-service &
  
  # Get and run a sample OpenXR application
  wget https://gitlab.freedesktop.org/wallbraker/apps/-/raw/main/VirtualGround-x86_64.AppImage
  chmod +x VirtualGround-x86_64.AppImage
  ./VirtualGround-x86_64.AppImage normal

• Use a real device in Monado.

  When using a real device driver you might want to enable the XRT_DEBUG_GUI=1 and SLAM_UI=1 environment variables to show debug GUIs of Monado and Basalt respectively.

  Monado has a couple of drivers supporting SLAM tracking (and thus Basalt). Most of them should work without any user input.

  • WMR (troubleshoot)
  • Rift S (might need to press "Submit to SLAM", like the Vive Driver).
  • Northstar / DepthAI (This hand-tracking guide has a depthai section).
  • Vive Driver (Valve Index) (read before using)
  • RealSense Driver (setup).

Development

If you want to set up your build environment for developing and iterating on Basalt, see the development guide.