CosmoScout VR is a modular virtual universe which lets you explore, analyze and present huge planetary datasets and large simulation data in real-time.
CosmoScout uses C++17 and OpenGL. It can be build on Linux (gcc or clang) and Windows (msvc). Nearly all dependencies are included as git submodules, please refer to the section Build Instructions in order to get started.
We try to add as many comments to the source code as possible. The number of source code lines and comment lines above is computed with the script cloc.sh. This script only counts real comments. Any dumb comments (such as copy-right headers or stuff like /////////) are not included in this number.
Features
CosmoScout VR is research software which is still under heavy development and changes on a daily basis. Many features are badly documented, it will crash without warning and may do other unexpected things. We are working hard on improving the user experience - please report all issues and suggestions you have!
Below is a rough sketch of the possibilities you have with CosmoScout VR. While this list is far from complete it provides a good overview of the current feature set.
- Solar System Simulation
- Positioning of celestial bodies and space crafts based on SPICE
- Rendering of highly detailed level-of-detail planets based on WebMapServices (with csp-lod-bodies)
- Rendering of configurable atmospheres (Mie- and Rayleigh-scattering) around planets (with csp-atmospheres)
- Physically based rendering of 3D satellites (with csp-satellites)
- Rendering of Tycho, Tycho2 and Hipparcos star catalogues (with csp-stars)
- Rendering of orbits and trajectories based on SPICE (with csp-trajectories)
- Rendering of shadows
- HDR-Rendering
- Flexible User Interface
- Completely written in JavaScript with help of the Chromium Embedded Framework
- Main UI be drawn in screen- or world-space
- Web pages can be placed on planetary surfaces
- Interaction works both, in VR and on Desktop
- Clear API between C++ and JavaScript
- Cross-Platform
- Runs on Linux
- Runs on Windows
- Runs on MacOS
- System Architecture
- Plugin-based - most functionality is loaded at run-time
- Network synchronization of multiple instances
- Hardware device support - CosmoScout VR basically supports everything which is supported by ViSTA and VRPN. The devices below are actively supported (or planned to be supported).
- Mouse
- Keyboard
- HTC-Vive
- ART-Tracking systems
- 3D-Connexion Space Navigator
- Multi-screen systems like tiled displays or CAVE's
- Multi-screen systems on distributed rendering clusters
- Side-by-side stereo systems
- Quad-buffer stereo systems
- Anaglyph stereo systems
- Game Pads like the X-Box controller
Plugins for CosmoScout VR
CosmoScout VR can be extended via plugins. In fact, without any plugins, CosmoScout VR is just a black and empty universe. Here is a list of available plugins.
| Official Plugins | Description | Screenshot |
|---|---|---|
| csp-anchor-labels | Draws a click-able label at each celestial anchor. When activated, the user automatically travels to the according body. The size and overlapping-behavior of the labels can be adjusted. |  |
| csp-atmospheres | Draws atmospheres around celestial bodies. It calculates single Mie- and Rayleigh scattering via raycasting in real-time. |  |
| csp-fly-to-locations | Adds several quick travel targets to the sidebar. It supports shortcuts to celestial bodies and to specific geographic locations on those bodies. |  |
| csp-lod-bodies | Draws level-of-detail planets and moons. This plugin supports the visualization of entire planets in a 1:1 scale. The data is streamed via Web-Map-Services (WMS) over the internet. A dedicated MapServer is required to use this plugin. |  |
| csp-measurement-tools | Provides several tools for terrain measurements. For example, it supports the measurement of distances, height profiles, volumes or areas. |  |
| csp-rings | Draws simple rings around celestial bodies. The rings can be configured with a inner and a outer radius and a texture. |  |
| csp-satellites | Draws GTLF models at positions based on SPICE data. It uses physically based rendering for surface shading. |  |
| csp-sharad | Renders radar datasets acquired by the Mars Reconnaissance Orbiter. The SHARAD profiles are rendered inside of Mars, the Martian surface is made translucent in front of the profiles. |  |
| csp-simple-bodies | Renders simple spherical celestial bodies. The bodies are drawn as an ellipsoid with an equirectangular texture. |  |
| csp-stars | Draws 3D-stars loaded from catalogues. For now, it supports the Tycho, the Tycho2 and the Hipparcos catalogue. |  |
| csp-trajectories | Draws trajectories of celestial bodies and spacecrafts based on SPICE. The color, length, number of samples and reference frame can be configured. |  |
Getting Started
We are happy to receive contributions to CosmoScout VR in the form of merge requests via Github. Feel free to fork the repository, implement your changes and create a merge request to the develop branch.
Further information on how to contribute can be found in CONTRIBUTING.md.
Build Instructions
CosmoScout VR can be build in debug and release mode on Linux and Windows. Travis CI is used for continuous integration.
| Branch | Travis Build Status |
|---|---|
| master |   |
| develop | |
Below you find the generic build instructions. Most dependencies are included as git submodules. You will only need a copy of CMake (version 3.12 or greater), Boost (version 1.69 or greater) and a recent C++ compiler (gcc 8, clang 5 or msvc 19). For the compilation of the externals Python is also required.
Linux
On Linux, one can either use the provided shell scripts (make_release.sh and make_debug.sh) or build the software manually using CMake. Using the provided scripts is easy and definitely the recommended way.
In any way, first you have to compile the dependencies. This step only has to be done once.
git clone git@github.com:cosmoscout/cosmoscout-vr.git
cd cosmoscout-vr
git submodule update --init
./make_externals.shThis will clone the repository to cosmoscout-vr configure and build all externals in cosmoscout-vr/build/linux-externals and will install them to cosmoscout-vr/install/linux-externals. For a minimal setup you will need some data sets which are not included in this git repository. Run this script to download the data to cosmoscout-vr/data:
./get_example_data.shNow you can compile CosmoScout VR:
./make_release.shThis will configure and build CosmoScout VR in cosmoscout-vr/build/linux-release and will install it to cosmoscout-vr/install/linux-release. The application can be executed with:
cd install/linux-release/bin
./start.shIf you wich, you can delete the directories build and install at any time in order to force a complete reconfiguration or re-installation.
For manual compilation follow the steps outlined in make_release.sh or make_debug.sh.
Windows
For Windows, there are batch scripts (make_release.bat and make_debug.bat) which can be used in the same way as the scripts for Linux:
First you have to compile the dependencies. This step only has to be done once. Run the commands below from the Visual Studio Developer Command Line:
git clone git@github.com:cosmoscout/cosmoscout-vr.git
cd cosmoscout-vr
git submodule update --init
make_externals.batThis will clone the repository to cosmoscout-vr configure and build all externals in cosmoscout-vr\build\windows-externals and will install them to cosmoscout-vr\install\windows-externals. For a minimal setup you will need some data sets which are not included in this git repository. Run this script to download the data to cosmoscout-vr\data:
get_example_data.batNow you can compile CosmoScout VR. On Linux, boost is usually found automatically by CMake, on Windows you have to provide the BOOST_ROOT path. Replace the path in the command below to match your setup!
set BOOST_ROOT=C:\local\boost_1_69_0
make_release.batThis will configure and build CosmoScout VR in cosmoscout-vr\build\windows-release and will install it to cosmoscout-vr\install\windows-release. The application can be executed with:
cd install\windows-release\bin
start.batIf you wich, you can delete the directories build and install at any time in order to force a complete reconfiguration or re-installation.
Using the application
Navigation: There are several ways for interacting with the planet. Currently mouse, keyboard and space navigator are supported. More input devices can be added via VRPN. The mouse navigation is still in development - while it is already quite useful, the user experience may be improved.
Keyboard Shortcuts: The most important one is Alt-Enter which will toggle full-screen mode. W, A, S, D will move the virtual camera; Q and E can be used to control the roll; R and F can be used to control the altitude. All other shortcuts can be shown by pressing ?. They will be printed to the console window.
User Interface: When you start CosmoScout VR, you will see several user interface elements. The top bar shows information regarding your current camera position, the position of the mouse pointer on the planets surface and the current simulation time (UTC). In addition, there are some buttons controlling the simulation time.
On the left hand side is the main menu. Here you can select which datasets are shown, manipulate the surface visualization, add annotations, fly to pre-defined locations and perform various other tasks.
More in-depth information and some tutorials will be provided soon.
Complete List of Dependencies
The list below contains all dependencies of CosmoScout VR. Besides Boost, all of them are included either as git submodules or directly in the source tree. Some of the dependencies are only required by some plugins.
| Engine Dependencies | Description | License |
|---|---|---|
| Boost (chrono, filesystem, date_time) | Used for time conversions and file system operations. | Boost Software License |
| c-ares | A dependency of curl, used for asynchronous DNS requests. | MIT |
| Chromium Embedded Framework | For the Webkit based user interface. | BSD |
| Curl | Library for downloading stuff from the Internet. | MIT style |
| CurlPP | C++ wrapper for curl. | MIT style |
| FreeGlut | Windowing toolkit dependency of OpenSG. | MIT |
| glew | OpenGL extension wrangler. | Modified BSD |
| glm | Math library used throughout CosmoScout. | Happy Bunny / MIT |
| JsonHPP | Parses json files in C++. | MIT |
| LibTiff | For .tiff image format support. | BSD-like |
| OpenSG | Scenegraph used as backend by Vista. | LGPL |
| OpenVR | Adds support for the HTC-Vive. | BSD 3-Clause |
| SPICE | Library to compute positions of celestial objects. | Custom License |
| STBImage | Library for loading .jpg and .png files. | Public Domain |
| Vista | VR-Framework for scenegraphs, distributed rendering and low-level VR-device access. | LGPL |
| VRPN | Used for supporting various hardware devices. | Boost Software License |
| zlib | Dependency of Vista. | MIT style |
| UI Dependencies | Description | License |
| Alegreya Sans Font | This font is used for the CosmoScout VR logo. | Open Font License |
| Bootstrap Date Picker | The calendar in the user interface. | Apache License 2.0 |
| D3.js | Used for some tools (like path measurement) to draw graphs in the user interface. | BSD 3-Clause |
| fuzzyset.js | Used for the location search on other planets and moons. | BSD |
| jQuery | JavaScript library which is used extensively in the user interface. | MIT |
| Material Icons | Icon set uses in the user interface. | Apache License 2.0 |
| MaterializeCSS | CSS-toolkit used in the user interface. | MIT |
| noUiSlider | JavaScript library for advanced sliders. | WTFPL |
| Ubuntu Font | This font is used in the user interface of CosmoScout VR. | Ubuntu font licence |
| Runtime Dependencies | Description | License |
| Apache built by Apachehaus | This is a pre-compiled apache server for windows which can be used to run your own Mapserver. Only required by the csp-lod-bodies plugin. |
Apache License 2.0 |
| GDAL | Dependency of the Mapserver. Only required by the csp-lod-bodies plugin. |
X11/MIT |
| Mapserver | Used to provide map data over the internet. Only required by the csp-lod-bodies plugin. |
MIT |
| proj.4 | The csp-lod-bodies requires a special version of this library to be used by the Mapserver. |
MIT |
Credits
The icons and badges in this README.md are from icons8.com and shields.io.
MIT License
Copyright (c) 2019 German Aerospace Center (DLR)
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.