Getting Started

The ILLIXR application 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
    • 20.04
    • 22.04
  • Fedora[^1]
    • 37
    • 38
  • CentOS[^1]
    • stream9

[^1]: Primary development is aimed at Ubuntu systems, full support for Fedora and CentOS may lag behind.

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


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 prerequesite 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.

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. 
Note that 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).



    
    





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_GL=ON to build the timewarp_gl plugin). Any number of plugins can be specified on the command line in this fashion.
    • 



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. Note: 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
- display_vk
- fauxpose
- gldemo
- ground_truth_slam
- gtsam_integrator
- native_renderer
- offline_cam
- offline_imu
- offload_data
- offload_vio.device_rx
- offload_vio.device_tx
- offload_vio.server_rx
- offload_vio.server_tx
- openni
- openvins
- passthrough_integrator
- pose_lookup
- pose_prediction
- realsense
- record_imu_cam
- record_rgb_depth
- rk4_integrator
- timewarp_gl
- timewarp_vk
- vkdemo
- zed


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 &lt;&gt; indicate
an infix specifying the build type, for Debug use dbg, for Release use opt, for RelWithDebInfo use optdbg)


    

  • --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, ??
    • 

  • -p,--plugins=<>, comma separated list of plugins to use (case sensitive, all lowercase, no spaces)
    • 

  • -r,--run=<>, comma separated list of plugins to use (case sensitive, all lowercase, no spaces), supersedes plugins entry.  This is only necessary if a plugin builds more than one library (e.g. offload_vio builds 4 libraries) as each must be loaded individually.
    • 

  • -y,--yaml<>, the profile file to use which specifies some or all of the above arguments (e.g. the generated illixr.yaml)
    • 

  • --vis, the visualizer to use (openvins currently)
    • 



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


Profile file format


An example of a YAML profile file is


plugins: timewarp_gl,gldemo,ground_truth_slam,offload_vio
run: timewarp_gl,gldemo,ground_truth_slam,offload_vio.device_rx
visualizers: openvins
duration: 5
data: data/mav0
demo_data: demo_data
build_type: Debug
install_prefix: /home/user/illixr
enable_offload: true
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.
    

    • 

  • 

    run
: Comma separated list of plugins (case sensitive) which are used at run time. This is only needed in cases like offload_vio where multiple plugin libraries are built by a single plugin, but must be loaded individually. (e.g. offload_vio.server_rx)
    

    • 

  • 

    visualizers
: Comma separated list of visualizers to build or load at runtime (currently openvins is available). At runtime, if multiple visualizers are listed, only the first one will be used.
    

    • 

  • 

    duration
: The duration to run ILLIXR for in seconds.
    

    • 

  • 

    data
: Path to the data file to dowload (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)
    

    • 

  • 

    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.
    

    • 

  • 

    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
: ? Default is false
    

    • 



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).


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.


Rationale


    

  • The current system can use profile files to control everything from the build to running ILLIXR, inkeeping 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.