Skip to content

Latest commit

 

History

History
1051 lines (1014 loc) · 30.1 KB

configuring.md

File metadata and controls

1051 lines (1014 loc) · 30.1 KB
Raw

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",
  "fileLogLevel": "debug",
  "consoleLogLevel": "trace",
  "screenLogLevel": "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.

  • "fileLogLevel", "consoleLogLevel" and "screenLogLevel": 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".

  • "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
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
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 ›