Skip to content

Getting Started

ILLIXR is configured and built via CMake. The CMake system checks for required dependencies, builds each requested plugin, builds the main ILLIXR binary, and (optionally) installs these components.

ILLIXR currently only builds on Linux systems, and has been tested on the following configurations:

  • Ubuntu
    • 22.04
    • 24.04
  • Fedora1
    • 38+

Other versions of these operating systems may work, but will likely require some manual installation of dependencies. For other Linux distributions (e.g. RHEL) it will require significant manual installation of dependencies as many are not available in the distribution repos. The instructions below are a generalized version.

Building ILLIXR

Clone the repository

git clone https://github.com/ILLIXR/ILLIXR --single-branch

This will clone only the default branch, if you want all branches then remove the --single-branch flag.

Install dependencies

There are two levels of dependencies in ILLIXR: those that are required for any type of build, and those that are required only for specific plugins.

Select your operating system and version

ILLIXR may compile with other versions of the above operating systems, but some of the necessary prerequisite packages are not supplied by the OS repos and will need to be compiled by hand. You should be able to use the package and cmake commands for other versions of the same OS (other than the missing packages) to compile ILLIXR. RHEL is not supported at this time as many of the prerequisite packages are not natively available. You will also need to have a C++ compiler installed (gcc, clang, etc.) as well as a generator (make, ninja, etc.) and CMake 3.22 or newer (installation is os dependent).

Pick the ILLIXR plugins you want to use

Include virtualization support:
See ILLIXR Under Virtualization for details.

Use the following to install the dependencies for the selected plugins:


Build command

Use the following to build and install ILLIXR. You can specify the install location by giving the path to CMAKE_INSTALL_PREFIX. If you want the default install path then do not add the option to the command line.

Warning

If your install prefix requires sudo privileges then you will need to run both the build and install under sudo (this is due to the way cmake builds and installs some of the pre-packaged dependencies during the build phase).

Some ILLIXR plugins rely on code that falls under the GNU General Public License (GPL) v3.0 or GNU Lesser General Public License (LGPL) v2.1. If you do not wish to build these codes you can select to exclude them below (or add -DNO_GPL=ON or -DNO_LGPL=ON to your cmake command line, NO_LGPL=ON implies the same for NO_GPL).

No GPL code
No LGPL code

Common CMake command line arguments (always prepend with a -D):

  • CMAKE_INSTALL_PREFIX The root path to install the libraries and binary to. This defaults to /usr/local.
  • CMAKE_BUILD_TYPE The build type to do: Debug, Release, RelWithDebInfo
  • YAML_FILE The profile file of plugins to build and install. The default is None, meaning plugins should be specified individually on the command line.
  • USE_<PLUGIN_NAME>=ON Build the specifically named plugin (e.g -DUSE_TIMEWARP_VK=ON to build the timewarp_vk plugin). Any number of plugins can be specified on the command line in this fashion.
  • BUILD_DOCS Set to ON to enable building the documentation.

Documentation Prerequisites

Building the documentation requires Doxygen and mkdocs(>= v1.5) to be installed, both of which are typically available from OS packages. Additionally, we utilize the material, mkdocs-material-extensions, mkdocs-get-deps, mkdocs-include-markdown-plugin, PyMdown, Pygments, mkdoxy, and mkdocs-glightbox python packages, which can be installed via pip using docs/requirements.txt.

An alternate to specifying the plugins as command line arguments is to create a YAML file which specifies the plugins to build. Using -DYAML_FILE=&lt;FILE_NAME&gt; as the command line argument specifying the YAML file to use.

You may need to specify the full path to the YAML_FILE

See profile for the format.

The current list of plugins is:

  • audio_pipeline
  • debugview
  • depthai
  • fauxpose
  • gldemo
  • ground_truth_slam
  • gtsam_integrator
  • hand_tracking
  • hand_tracking.viewer
  • hand_tracking_gpu
  • lighthouse
  • native_renderer
  • offline_cam
  • offline_imu
  • offload_data
  • offload_rendering_client
  • offload_rendering_server
  • offload_vio.device_rx
  • offload_vio.device_tx
  • offload_vio.server_rx
  • offload_vio.server_tx
  • openni
  • openvins
  • openwarp_vk
  • openwarp_vk.monado
  • orb_slam3
  • passthrough_integrator
  • pose_lookup
  • pose_prediction
  • realsense
  • record_imu_cam
  • record_rgb_depth
  • rk4_integrator
  • tcp_network_backend
  • timewarp_gl
  • timewarp_gl.monado
  • timewarp_vk
  • timewarp_vk.monado
  • vkdemo
  • webcam
  • zed
  • zed.data_injection

The CMake process will also create a YAML file call illixr.yaml which can be used as input to the binary.

Running ILLIXR

To run the ILLIXR binary just call main.<>.exe with any of the following command line arguments. (the <> indicate an infix specifying the build type, for Debug use dbg, for Release use opt, for RelWithDebInfo use optdbg)

  • -p,--plugins=<>, comma separated list of plugins to use (case sensitive, all lowercase, no spaces)
  • -y,--yaml=<>, the profile file to use which specifies some or all of the above arguments (e.g. the generated illixr.yaml)
  • --, you can specify any variable the ILLIXR uses on the command line. Common ones are:
  • --duration=<>, the duration to run for in seconds (default is 60)
  • --data=<>, the data file to use
  • --demo_data=<>, the demo data to use
  • --enable_offload
  • --enable_alignment
  • --enable_verbose_errors, give more information about errors
  • --enable_pre_sleep, force ILLIXR to sleep for the given number of seconds before starting the plugins (this is useful for attaching a debugger)

Regarding parameters for the binary, the following priority will be used: 1. If the parameter is specified on the command line it will have the highest priority 2. If the parameter has a value in the yaml file this value will only be used if it is not specified on the command line (second priority) 3. If the parameter has a value as an environment variable this value will only be used if it is not specified on the command line nor yaml file

Please refer to the display backend for instructions on setting display-related environment variables.

For specific usage instructions, refer to the README files of the respective plugins.

Profile file format

An example of a YAML profile file is 

plugins: pose_lookup,timewarp_vk,vkdemo,native_renderer
build_type: Debug
install_prefix: /home/user/illixr
env_vars:
  ILLIXR_RUN_DURATION: 5
  DATA: data/mav0
  DEMO_DATA: demo_data
  ENABLE_OFFLOAD: false
  ENABLE_ALIGNMENT: false
  ENABLE_VERBOSE_ERRORS: false
  ENABLE_PRE_SLEEP: false

Where the entries are defined as (* indicates required field):

  • plugins * : Comma separated list of plugins (case-sensitive) to build or load at runtime.

  • build_type : The type of build to perform (Debug, Release, or RelWithDebInfo). Ignored at run time.

  • install_prefix : The root path to where the compiled libraries and binaries should be installed. (e.g. specifying /home/user will install libraries in /home/user/lib and binaries in /home/user/bin).

    Note

    The prefix is also used for installing any packages that were downloaded and build from external repositories (e.g. DBoW2, GTSAM, etc). At runtime this path is added to LD_LIBRARY_PATH to aid in finding the plugin libraries.

  • env_vars : environment variables to use, any environment variable ILLIXR uses can be set here and will be valid during program execution.

In general, you should not edit a profile file directly. The exception to this is when you are testing things on your own machine. Profile files are generated automatically from the master profiles/plugins.yaml during the cmake configuration stage. This is done so that any changes to a profile or the addition or removal of a plugin can be managed from a single file. The build system will generate an illixr.yaml file which contains entries from the command line and any input profile file and can be freely edited (it is generated every time cmake is called).

Environment Variables

ILLIXR and several of its dependencies use environment variables to steer processing and define quasi-constant values. Traditionally, one would use std::getenv and std::setenv to get and set these items. However, in ILLIXR the switchboard acts as an interface to these functions with get_env (returns std::string), get_env_bool (returns bool), get_env_char (returns char*), and set_env. Using the switchboard interfaces allows for environment variables to be set from the command line and/or yaml file. It is strongly encouraged to the switchboard interface wherever possible. Any items given on the command line which do not match expected command line arguments are considered to be environment variables. For example:

main.dbg.exe --yaml=my.yaml --DATA_SOURCE=/home/my/data --PROCESS_DATA

This will set env environment variables DATA_SOURCE to /home/my/data and PROCESS_DATA to True. For yaml files, any items not in the expected set will be considered to be environment variables. For example:

plugins: fauxpose,timewarp_vk,vkdemo,debugview,audio_pipeline
enable_offload: false
env_vars:
  DATA_SOURCE: /home/my/data
  PROCESS_DATA: true

Here, the keywords plugins and enable_offload are ignored, as they are expected options. The DATA_SOURCE and PROCESS_DATA entries will cause environment variables to be set to the respective values.

Note

The names and values of the environment variables are case-sensitive.

Note

The get_env_bool considers any of 'y', 'yes', 'true', 'on' (case-insensitive), and "1" to be true.

Common Environment Variables

  • illixr_run_duration : The duration to run ILLIXR for in seconds.

  • data : Path to the data file to download (build step) or use at runtime. If a URL is given (must start with http or https) the file will be downloaded and extracted; the path to the extracted data will be put in the illixr.yaml file.

  • demo_data : The path to the demonstration data to use at runtime (ignored by build steps)

  • enable_offload : ? Default is false

  • enable_alignment : ? Default is false

  • enable_verbose_errors : Controls the verbosity of error messages. Default is false

  • enable_pre_sleep : Force ILLIXR to sleep for the given number of seconds before starting the plugins (this is useful for attaching a debugger), Default is 0, indicating no sleeping.

Each plugin can define environment variables to use. See the documentation of each plugin for details.

ILLIXR Graphics Backends

ILLIXR currently supports both OpenGL and Vulkan backends (indicated as gl and vk in the config suffixes). Since some plugins should behave differently (and compile differently) based on what backend is being used, it's important to run make clean if you want to try swapping between the two backends.

Warning

The use of the OpenGL back end is in the process of being deprecated. Thus gl based plugins are not guaranteed to work in every instance.

Rationale

  • The current system can use profile files to control everything from the build to running ILLIXR, in keeping with the DRY principle. However, for maximum flexibility control can also be done at the command line level as well.

Philosophy

  • Each plugin should not have to know or care how the others are compiled. In the future, they may even be distributed separately, just as SOs. Therefore, each plugin needs its own build system.

  • Despite this per-plugin flexibility, building the 'default' set of ILLIXR plugins should be extremely easy.

  • It should be easy to build in parallel.

  • Re-running make (and optionally cmake first) will only rebuild those parts of the code with have changed.

Next Steps

Try browsing the source for the runtime and provided plugins. The source code is divided into components in the following directories:

  • ILLIXR/src/: A directory holding the implementation for loading and interfacing plugins. This directory contains Spindle.

  • ILLIXR/include/illixr/: A directory holding resources and utilities available globally to all plugins. This directory contains the interfaces for Switchboard and Phonebook.

  • ILLIXR/plugins/<plugin_dir>/: A unique directory for each plugin. Most of the core XR functionality is implemented via plugins. See Default Components for more details.

If you edit any of the source files, the CMake system will detect and rebuild the respective binary the next time it runs. If you want to add your own plugin, see Writing Your Plugin.

  1. Primary development is aimed at Ubuntu systems, full support for Fedora may require extra work on the users part. ↩