The Navigation and Viewing Framework was designed to enable users to create a variety of viewing setups using different input devices and user types in the VR lab at Bauhaus University Weimar. It is based on the Virtual Reality framework avango and the rendering engine guacamole. In order to specify a concrete viewing setup within the framework, two types of configurations (located in subdirectory configs) are used.

Display configuration (Python)
A display is a physical medium which can show images for zero, one or multiple mono and stereo users. Displays that are available within the framework can be specified within the python file display_config.py. There, the displays list at the end of the file contains all parametrized displays. For each display, a hostname, a name, the resolution, the possible displaystrings, the shutter timings / values, the stereo mode, the physical size and the transformation can be specified. In case of larger displays, also warpmatrices can be set. Once a display is added to this list, it can be used using the XML viewing configuration files described in the following.

Note: The framework supports an interactive assignment of display slots to shutter glasses worn by users. In this case, users may obtain multiple slots of a single display in order to see a brighter image. If this functionality is not desired, it can be switched off using the bool INTELLIGENT_SHUTTER_SWITCHING in the end of display_config.py.

Viewing configuration (XML)

General remarks
The framework comes with some example configuration files located in ./configs. In order to start the application, one viewing configuration needs to be specified: ./start-all.sh CONFIG_FILE. In the following, it is explained how exactly such configuration files can be written.

Overall structure
The configuration file consists of three main parts included in the <setup>-tag: the specification of global settings, the registration of devices and their corresponding platforms and the registration of users. Global settings include options that are valid for all users and devices which are going to be registered later on. In the device section, all the desired input devices are named and it is said where they should be initially placed in the virutal world. Finally, one specifies the different users to be created and appends them to a platform registered before.

Global settings
The specification of global settings is done within the <global>-tag and should be done at the beginning of the file. In the following, all available settings will be illustrated.

<animatecoupling>
A boolean saying if a rotation center interpolation during the coupling process between platforms is desired. The default is set to False.
Usage example: <animatecoupling>True</animatecoupling>

Registration of devices and platforms
Every time a device is registered, a corresponding platform in the virtual world is created which is moved and controlled by this device. All the settings for devices and platforms are done within the <device>-tag, one for each device that should be registered. Please note that not all of the following options must be made. In case they are missing, the mentioned default values are applied.

<type>
A string indicating which type the new device is. To be chosen from "KeyboardMouse", "Spacemouse", "XBoxController", "OldSpheron" and "NewSpheron".
Usage example: <type>XBoxController</type>

<inputsensor>
A string indicating the name on which this device was registered in daemon.py. Not applicable for device type "KeyboardMouse", as it is assumed that just one keyboard and one mouse are connected to the computer.
Usage example: <inputsensor>device-xbox-1</inputsensor>

<trackingstation>
A string indicating the name on which this device's tracking target was registered in daemon.py. If this attribute is not supplied, the default tracking values are taken from the <notrackingposition> tag specified later.
Usage example: <trackingstation>tracking-dlp-glasses-1</trackingstation>

<display>
Name of the display on which this platform is to be shown. When this attribute is supported multiple times, the platform is shown on both displays, each illustrating the correct view into the scene according to the transformation specified in the display configuration. The name must fit to an instance of the Display class in the displays list.
Usage example: <display>small_powerwall</display>

<avatartype>
String indicating the type of avatars to be used for illustrating the users standing on this platform. If set to "None", no device, screen and user avatars will be displayed for this platform. To be chosen. Otherwise, "joseph" (robot avatar) is specified.
Usage example: <avatartype>joseph</avatartype>

<transmitteroffset>
This sets the transmitter offset to be applied by the framework for this platform. The default is set to (0.0, 0.0, 0.0, 0.0, 0.0, 0.0).
Usage example: <transmitteroffset><x>0.0</x><y>0.0043</y><z>1.6</z><rx>0.0</rx><ry>0.0</ry><rz>0.0</rz><transmitteroffset>

<notrackingposition>
This is the default position to be applied if the device or a user on the platform has no tracking station specified. The default is set to (0.0, 1.5, 1.0). Usage example: <notrackingposition><x>0.0</x><y>1.75</y><z>1.5</z></notrackingposition>

<platformpos>
Three dimensional coordinates on where to place the newly created platform in the virtual world. By default, the position (0.0, 0.0, 0.0) is assumed.
Usage example: <platformpos><x>0.0</x><y>0.0</y><z>6.0</z></platformpos>

<platformrot>
The starting yaw angle of the newly created platform. By default, a rotation of 0 degrees is assumed.
Usage example: <platformrot><yaw>180.0</yaw></platformrot>

<scale>
The starting scaling factor of the newly created platform. By default, a scaling of 1.0 is assumed.
Usage example: <scale>10.0</scale></platformrot>

<platformsize>
The physical size of the platform in meters (e.g. size of the tracking space). The default is set to 1.0 m x 1.0 m.
Usage example: <platformrot><yaw>0.0</yaw></platformrot>

<groundfollowing>
This tag specifies two attributes of the ground following (gravity) algorithm to be used for this platform. The first attribute "activated" is a boolean saying if gravity should be activated during startup. The second attribute "raystartheight" indicates from which height the ray is shot down to determine the intersection. The default values are False and 0.75.
Usage example: <groundfollowing><activated>True</activated><raystartheight>0.75</raystartheight></groundfollowing>

<movementtraces>
A boolean saying if the platform should leave traces behind them. The default is set to False.
Usage example: <movementtraces>True</movementtraces>

Registration of users
This section shows which attributes are needed in order to create a user in the virtual world. The settings must be done in the <user>-tag for each user seperately.

<vip>
Boolean value saying if this user is a very important person. VIP are preferred during the display slot assignment procedure. The default is set to False.
Usage example: <vip>True</vip>

<glasses>
Number of the shutter glasses worn by the user. Used to set the correct timings and values after the slot assignment.
Usage example: <glasses>4</glasses>

<headtrackingstation>
A string indicating the name on which this user's tracking target was registered in daemon.py. If this attribute is not supplied, the default tracking values from the platform are applied.
Usage example: <type>DesktopUser</type>

<startplatform>
An integer number to indicate to which platform the new user should be appended to during the startup procedure. Corresponds to the order in which the devices were created, the counting starts from 0.
Usage example: <startplatform>2</startplatform>

<warnings>
A boolean indicating if the user should be warned by fences when he or she is close to the physical borders of the platform.
Usage example: <warnings>True</warnings>

Summary
Now you basically already know how to use the Navigation and Viewing framework. However, if you are interested in understanding and modifying the concrete functionalites, the following pages provide an overview of all files, classes, attributes and functions used in and programmed for this framework.

Contact
André Kunert: andre.nosp@m..kun.nosp@m.ert@u.nosp@m.ni-w.nosp@m.eimar.nosp@m..de
Joshua Reibert: joshu.nosp@m.a.re.nosp@m.ibert.nosp@m.@uni.nosp@m.-weim.nosp@m.ar.d.nosp@m.e
Tim Weißker: tim.w.nosp@m.eiss.nosp@m.ker@u.nosp@m.ni-w.nosp@m.eimar.nosp@m..de