Configuring CosmoScout VR

When you launch CosmoScout VR via the start scripts (start.sh or start.bat), two main configuration files are passed as command line arguments.

The first (simple_desktop.json) configures your virtual scene. This includes for example the simulation time, the observer position in space and the configuration for each and every plugin. The second file (vista.ini) configures your hardware setup - your input devices, the screens to render on, the setup of your render cluster and much more.

The next two chapters describe both files in more detail.

1. Scene Configuration

The most simple scene configuration file contains the JSON data below. It will produce an empty universe with the virtual camera being centered on where usually the earth would have been. In the following, the individual parameters are explained and the required steps for populating the black universe are outlined.

{
  "startDate": "today",
  "resetDate": "today",
  "minDate": "1950-01-02 00:00:00.000",
  "maxDate": "2049-12-31 00:00:00.000",
  "logLevelFile": "debug",
  "logLevelConsole": "trace",
  "logLevelScreen": "info",
  "logLevelGL": "info",
  "observer": {
    "center": "Earth",
    "frame": "IAU_Earth",
    "position": [0, 0, 25000000],
    "rotation": [0, 0, 0, 1]
  },
  "spiceKernel": "../share/config/spice/simple.txt",
  "widgetScale": 0.6,
  "enableMouseRay": false,
  "sceneScale": {
    "minScale": 1,
    "maxScale": 100000000000000000,
    "closeVisualDistance": 1.6,
    "farVisualDistance": 0.7,
    "closeRealDistance": 1.6,
    "farRealDistance": 10000000,
    "lockWeight": 0.1,
    "trackWeight": 0.0002,
    "minObjectSize": 10000.0
  },
  "anchors": {},
  "bookmarks": [],
  "plugins": {}
}

"startDate": This should be either "today" or in the format "1950-01-02 00:00:00.000". It determines the initial simulation time.
"resetDate": This should be either "today" or in the format "1950-01-02 00:00:00.000". The simulation time will be set to this value when the reset button is clicked.
"minDate": This should be in the format "1950-01-02 00:00:00.000" and determines the left end of the timeline. You have to make sure that the loaded SPICE kernels are valid for this time range.
"maxDate": This should be in the format "2049-12-31 00:00:00.000" and determines the right end of the timeline. You have to make sure that the loaded SPICE kernels are valid for this time range.
"logLevelFile", "logLevelConsole", and "logLevelScreen": Adjust the verbosity of the log output written to cosmoscout.log, written to the command line and written to the on-screen console respectively. Should be one of "trace", "debug", "info", "warning", "error", "critical" or "off".
"logLevelGL": An additional log level which can be used to further restrict the log output of OpenGL calls. Should be one of "trace", "debug", "info", "warning", "error", "critical" or "off".
"observer": Specifies the initial position of the virtual camera. "center" and "frame" define the initial SPICE reference frame; "distance" (in meters), "longitude" and "latitude" (in degree) the 3D-position inside this reference frame. For more background information on SPICE reference frames, you may read this document.
spiceKernel: The path to the SPICE meta kernel. If you want to start experimenting with SPICE, you can read the SPICE-kernels-required-reading document. However, the included meta kernel contains already data for many of the solar system's bodies from 1950 to 2050.
"widgetScale": This factor specifies the initial scaling factor for world-space UI elements. You can modify this if in your screen setup the 3D-UI elements seem too large or too small.
"enableMouseRay": In a virtual reality setup you want to set this to true as it will enable drawing of a ray emerging from your pointing device.
"sceneScale": In order for the scientists to be able to interact with their environment, the next virtual celestial body must never be more than an arm’s length away. If the Solar System were always represented on a 1:1 scale, the virtual planetary surface would be too far away to work effectively with the simulation.
This JSON object controls how the virtual scene is scaled depending on the observer's position. This distance to the closest celestial body depends on the observer's real distance in outer space to the respective body. Take this as an example:
```
"sceneScale": {
  "minScale": 1,
  "maxScale": 100000000000000000,
  "closeVisualDistance": 1.6,
  "farVisualDistance": 0.7,
  "closeRealDistance": 1.6,
  "farRealDistance": 10000000,
  "lockWeight": 0.1,
  "trackWeight": 0.0002,
  "minObjectSize": 10000.0
},
```
If the observer is closer to a celestial body's surface than closeRealDistance (in meters), the scene will be shown in a 1:1 scale (that is 1:minScale) and the respective body will be rendered at a distance of closeVisualDistance (in meters). If the observer is farther away than farRealDistance (in meters) from any body, the scene will be shown in a 1:100000000000000000 scale (that is 1:maxScale) and the closest body will be rendered at a distance of farVisualDistance (in meters).
At any distance between closeRealDistance and farRealDistance, the values above will be linearly interpolated.
This JSON object also controls the automatic SPICE frame changes when the observer moves from body to body. The active body is determined by its weight which is calculated by its size and distance to the observer. When this weight exceeds trackWeight, the observer will follow the body's position. When this weight exceeds lockWeight, the observer will also follow the body's rotation.

"anchors": This item contains an object for each and every celestial anchor you are using later in the config. Take this as an example:

"anchors": {
  "Moon": {
    "center": "Moon",
    "frame": "IAU_Moon",
    "existence": ["1950-01-02 00:00:00.000", "2049-12-31 00:00:00.000"],
    "radii": [1000, 1000, 1000], // Optional, in meters. If not given, values from your SPICE kernels will be used
    "position": [0, 0, 0],       // Optional, in meters. Relative to the SPICE reference frame above.
    "rotation": [0, 0, 0, 1]     // Optional. Relative to the SPICE reference frame above.
    "scale": 1                   // Optional. Scales around the "position".
    "trackable": true            // Optional. If set to false, the observer will not try to follow CelestialBodies attached to this anchor.
  },
  ...
}

Now if you want to attach a simple body or a trajectory to this anchor, the configuration of the respective plugins will only refer to "Moon". The properties "center" and "frame" define the SPICE reference frame, "existence" should match at most the data coverage of your SPICE kernels. Keep in mind, that the dates are given UTC, your SPICE kernel's coverage is however most likely given in TDB which differs from UTC by several seconds.

"bookmarks": This list may contain events which will be shown on the timeline and in the sidebar. Take this as an example:

 "bookmarks": [
  {
    "name": "Mercury",
    "icon": "mercury.png",
    "location": {
      "center": "Mercury",
      "frame": "IAU_Mercury"
    }
  },
  {
    "name": "Apollo 17 Start",
    "description": "Start of the Apollo 17 mission from the Kennedy Space Center.",
    "color": [0.8, 0.8, 0.8],
    "location": {
      "center": "Earth",
      "frame": "IAU_Earth",
      "position": [-6717320.0, 3677613.0, 1137577.0],
      "rotation": [0.154, 0.634, 0.182, -0.735]
    },
    "time": {
      "start": "1972-12-07 05:33:57"
    }
  },
  ...
],

Except for "name", all properties are optional. You can supply a description, a color, a location (optionally with position and rotation) and a time.

"plugins": This item contains an object for each plugin. The name of the object must match the library name of the plugin. In the example below, CosmoScout VR will attempt to load a plugin library called ../share/plugins/libcsp-simple-bodies.so (..\share\plugins\csp-simple-bodies.dll on Windows).
```
"plugins": {
  "csp-simple-bodies": {
    "bodies": {
      "Moon": {
        "texture": "../share/resources/textures/moon.jpg"
      },
      ...
    }
  },
  ...
}
```
The content of the objects in "plugins" is directly passed to the loaded plugin. For more information on the configuration of the plugins, please refer to the repositories of the individual plugins. In the example above, a simple textured sphere will be attached to the celestial anchor "Moon" we defined earlier in the "anchors" object.

ℹ️ Tip: Since CosmoSout VR will ignore items in "plugins" for which no plugin library is found, an easy way to temporarily disable a plugin is modifying its name:
```
...
"#csp-simple-bodies": {
...
```
"gui": This is an optional top-level configuration which is required for virtual reality scenarios. If omitted, the UI is directly drawn to (and resized with) the window. However, in typical VR-scenarios you want to draw the UI somewhere onto a virtual screen. The "gui" object defines the size and position of this virtual screen. As an example, you can have a look at the provided simple_vive.json file:
```
"gui": {
  "heightMeter": 1.8,
  "heightPixel": 1200,
  "posXMeter": 0.0,
  "posYMeter": 1.2,
  "posZMeter": -1.0,
  "rotX": 0.0,
  "rotY": 0.0,
  "rotZ": 0.0,
  "widthMeter": 2.4,
  "widthPixel": 1600
}
```

2. ViSTA Configuration

🚧 Under Construction: This guide is still far from complete. We will improve it in the future.

Thanks to the ViSTA framework, it is possible to run CosmoScout VR on a desktop, on the HTC-Vive, a tiled display or a six-sided CAVE without any modifications to the source code. While this is very versatile, configuring ViSTA is also a very complex and involved topic. This guide will give you some information on how to get started.

ℹ️ Tip: If you need help configuring CosmoScout VR for your complex setup, we may be able to provide some help. Just get in touch via cosmoscout@dlr.de

The example configuration uses two further files (interaction.ini and display.ini) which are referenced by the main vista.ini. Every file except for the vista.ini is optional. If such a file is not provided, the vista.ini will be used as a fallback. This means, that all options are also valid for the vista.ini file. Each file has a specific section which is called SYSTEM which serves as an entry point.

⚠️ Warning: The lists of options below have been retrieved by reading the source code. It is incomplete and may be erroneous. Please fix anything you find! Most of the parameters are parsed by VistaSystem.cpp, VistaSystemConfigurators.cpp, VistaNewClusterMaster.cpp and VistaNewClusterSlave.cpp.

`vista.ini`

This is the entry file which is given as parameter to the cosmoscout executable. While you could put the entire configuration in this file, it is a good practice to modularize the configuration and use separate .ini-files for different aspects.

Section	Parameter	Type	Default Value	Notes
SYSTEM	INTERACTIONINI	filename	this file (e.g. vista.ini)
	INTERACTIONINI	filename	this file (e.g. vista.ini)
	INTERACTIONINI	filename	this file (e.g. vista.ini)
	CLUSTERINI	filename	this file (e.g. vista.ini)	Since the cluster configuration usually refers to sections of the display configuration, there are issues when both are put into a separate files. It is therefore advisable to use the same file given for DISPLAYINI here as well.

`display.ini`

This file describes your window geometry, projection and stereo mode. The default values depend on the used DisplayBridge. In most cases this means that they depend on OpenSG.

Section	Parameter	Type	Default Value	Notes
SYSTEM	WINDOWINGTOOLKIT	string	GLUT
SYSTEM	DISPLAYSYSTEMS	section name list
<NAME OF DISPLAYSYSTEM>	REFERENCE_FRAME	section name
	VIEWPORTS	section name list
	VIEWER_POSITION	vector3f	0, 0, 0
	VIEWER_ORIENTATION	euler angles	0, 0, 0
	LEFT_EYE_OFFSET	vector3f
	RIGHT_EYE_OFFSET	vector3f
	LOCAL_VIEWER	bool
	HMD_MODE	bool
	NAME	string	""
<NAME OF REFERENCE FRAME>	TRANSLATION	vector3f	0, 0, 0
	ROTATION	euler angles	0, 0, 0
	SCALE	float	1
	NAME	string	""
<NAME OF VIEWPORT>	WINDOW	section name
	PROJECTION	section name
	POSITION	vector2i	0, 0
	SIZE	vector2i	same as window size
	PASSIVE_BACKGROUND	bool	false	If set to true, the screen is not cleared between draws.
	NAME	string	""
<NAME OF WINDOW>	STEREO	bool	false	In order to enable stereo, you have to set this value as well as the STEREO_MODE value of the used projection.
	USE_ACCUM_BUFFER	bool
	USE_STENCIL_BUFFER	bool
	DRAW_BORDER	bool
	CONTEXT_VERSION	int
	DEBUG_CONTEXT	bool
	FORWARD_COMPATIBLE	bool
	POSITION	vector2i
	SIZE	vector2i
	FULLSCREEN	bool	false
	OFFSCREEN_BUFFER	bool
	MULTISAMPLES	int
	TITLE	string
	VSYNC	bool	true
	NAME	string	""
<NAME OF PROJECTION>	PROJ_PLANE_MIDPOINT	vector3f
	PROJ_PLANE_NORMAL	vector3f
	PROJ_PLANE_UP	vector3f
	PROJ_PLANE_EXTENTS	vector4d
	CLIPPING_RANGE	vector2d
	STEREO_MODE	string	MONO	Either FULL_STEREO, MONO, LEFT_EYE or RIGHT_EYE. In order to enable stereo, you have to set this value as well as the STEREO value of the used window.
	NAME	string	""

`graphics.ini`

This file sets some default OpenGL states. Except for the BACKGROUNDCOLOR it is not used by CosmoScout VR.

Section	Parameter	Type	Default Value	Notes
SYSTEM	GRAPHICSSECTION	section name
SYSTEM	DISPLAYACTIVE	bool	true	Enables the loading of 3D models given with a command line switch. "-loadmodel <file name>" will add the given model to the scenegraph when this option is set to true. Use "-scalemodel <value>" to adjust the model's size.
<NAME OF GRAPHICSSECTION>	LIGHTS	section name list
	SHOWCURSOR	bool
	BACKGROUNDCOLOR	vector3f		If not set in cpp code, the background color of the scene can be defined in the vista.ini / graphics.ini (if referenced in vista.ini) in the graphics section
<NAME OF LIGHT SECTION>	AMBIENTCOLOR	vector3f
	DIFFUSECOLOR	vector3f
	SPECULARCOLOR	vector3f
	DIRECTION	vector3f
	POSITION	vector3f
	ATTENUATION	vector3f
	INTENSITY	float
	TYPE	string		either DIRECTIONAL, POINT or SPOT

`interaction.ini`

This file specifies which ViSTA device drivers should be loaded and how the device's input data is fed to the application. The data-flow itself is modelled in separate .xml-files which you can find in the config/base/vista/xml directory.

Section	Parameter	Type	Default Value	Notes
SYSTEM	DRIVERPLUGINDIRS	list of directory names	. (the executable's directory)	Usually this should be set to ${VISTACORELIBS_DRIVER_PLUGIN_DIRS}
	DEVICEDRIVERS	section name list
	INTERACTIONCONTEXTS	section name list
	DUMPDFNGRAPHS	bool	false	Writes all graphs as dot files for debugging. The produced dot files can be viewed on linux with dot -Tpng <DOT_FILE> -ooutput.png
	WRITEDFNPORTS	bool	false
<NAME OF DEVICE DRIVER>	TYPE	string		This is used as base name of the driver library (there should be a libVistaTYPEDriver.so, a libVistaTYPEPlugin.so and a libVistaTYPETranscoder.so in your VISTACORELIBS_DRIVER_PLUGIN_DIRS)
	DRIVERPLUGIN	string		If specified, not libVistaTYPEPlugin.so is searched, but libDRIVERPLUGIN.so
	TRANSCODERPLUGIN	string		If specified, not libVistaTYPETranscoder.so is searched, but libTRANSCODERPLUGIN.so
	NAME	string	<NAME OF DEVICE DRIVER>	This is the name used in the DFN to reference the driver.
	PRIORITY	unsigned int	0
	DEPENDSON	driver name list
	SENSORS	section name list
	HISTORY	int	5
	DEFAULTWINDOW	bool	true
	DRIVERLOGGING
	PARAMETERS
	ATTACHONLY
	PROTOCOL
	CONNECTIONS
	IDENTIFICATION
<NAME OF SENSOR>	TYPE	string	""	Seems to be unsused
	NAME	string	<NAME OF SENSOR>
	RAWID	int		Reference the sensor with this ID of the driver. Often zero is used.
	HISTORY	int	as configured in the driver section	Has to be greater than one
<NAME OF INTERACTION CONTEXT>	ROLE
	PRIORITY	int	0	High priority is mapped to 8192, low priority to -1
	DELAYED_UPDATE	bool	false
	GRAPH	filename		This xml file contains the DFN description for this interaction context.
	RELOADTRIGGER	a key		Reload the graph by pressing this button
	DEBUGSTREAM	string	dot	Can be either dot, VSTR::OUT, VSTR::warn, VSTR::ERR, cout, cerr, clog, or a file name. The loaded graph will be printed to this stream.
	DEBUGTRIGGER	a key
	AUTODEBUG	bool	false
	ENABLED	bool	true

`cluster.ini`

The parameters presented here refer to the VistaNewClusterSlave and VistaNewClusterMaster classes. The deprecated VistaClusterSlave and VistaClusterMaster classes may use different parameters.

Section	Parameter	Type	Default Value	Notes
<NAME OF NODE>	NAME	string	<NAME OF NODE>	This section is used when given by the commandline argument "-newclusterslave <NAME OF NODE>" or "-newclustermaster <NAME OF NODE>". Some parameters are only useful when the node is executed in master mode.
	DISPLAYSYSTEMS	section name list
	SLAVES	section name list		Only valid for master node sections.
	DATASYNCTYPE	string	TCP	Either DUMMY, TCP/IP, ZEROMQ or INTERPROC.
	BARRIERTYPE	string	BROADCAST	Either DUMMY, TCP/IP, BROADCAST, MUTEX or ZEROMQ.
	SWAPSYNCTYPE	string	BROADCAST	Either DUMMY, TCP/IP, BROADCAST, BARRIER, GSYNC, MUTEX, NONE or ZEROMQ.
	FREEPORTS	port range
	DOGLFINISH	bool
	SLAVEIP	IP address		Only valid for slave node sections.
	SLAVEPORT	unsigned int		Only valid for slave node sections.
	ZEROMQ_ADDRESS	IP address
	ZEROMQ_PORTS	port range
	BROADCASTPORTS
	BROADCASTIP		""
	BROADCASTGROUPS		1
	MAX_ALLOWED_BARRIER_FAILURES	int	10
	DEBUG_OUTPUT
	DEBUG_PREPEND_TIMESTAMP	bool	true
	DEBUG_STREAM_NAME	string	"ClusterDebugging"
	DEBUG_OUTPUT_FILE	string	<DEBUG_STREAM_NAME>
	RECORD	string	""

3. Advanced Customization

While you can start by modifying the provided configuration files (simple_desktop.json and simple_vive.json), you will most likely end up with a bunch of configuration files which are very specific for your setup. Therefore you should not commit them to the source tree of CosmoScout VR - however, you can still use git for version control!

The trick is, to create a separate git repository for your configuration files and clone this repository to cosmoscout-vr/config/<your-custom-config-dir>. All directories in cosmoscout-vr/config except for the base directory are ignored by git (see .gitignore).

The CMakeLists.txt in cosmoscout-vr/config automatically collects adds all subdirectories. So you can install any scripts / configs / data files you like as part of CosmoScout's build process!

‹ Using CosmoScout VR ⌂ Help Index Contributing Guides ›

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

configuring.md

configuring.md

Configuring CosmoScout VR

1. Scene Configuration

2. ViSTA Configuration

`vista.ini`

`display.ini`

`graphics.ini`

`interaction.ini`

`cluster.ini`

3. Advanced Customization

Files

configuring.md

Latest commit

History

configuring.md

File metadata and controls

Configuring CosmoScout VR

1. Scene Configuration

2. ViSTA Configuration

vista.ini

display.ini

graphics.ini

interaction.ini

cluster.ini

3. Advanced Customization

`vista.ini`

`display.ini`

`graphics.ini`

`interaction.ini`

`cluster.ini`