README.md 6.21 KB
Newer Older
Flemming Stäbler's avatar
Flemming Stäbler committed
1
# Digital Earth Viewer
Flemming Stäbler's avatar
Flemming Stäbler committed
2
3
4
4D viewer for georeferenced data. Development is part of [Digital Earth](https://www.digitalearth-hgf.de). The Digital Earth Viewer was [presented at EuroVis 2021](https://youtu.be/iIRBpXOWuPg?t=123).

[Here](https://diglib.eg.org/bitstream/handle/10.2312/envirvis20211081/033-037.pdf) we present the software architecture and [here](https://diglib.eg.org/bitstream/handle/10.2312/envirvis20211082/039-042.pdf) we demonstrate a use case.
Valentin Buck's avatar
Valentin Buck committed
5

Valentin Buck's avatar
Valentin Buck committed
6
7
## License

Valentin Buck's avatar
Valentin Buck committed
8
9
Copyright Jens Greinert, Valentin Buck, Flemming Stäbler, Everardo Gonzalez, Jochen Mohrmann at the GEOMAR Helmholtz-Centre 2021.

Valentin Buck's avatar
Valentin Buck committed
10
11
12
The Digital Earth Viewer is licensed under the EUPL v.1.2.

This means for you:
Valentin Buck's avatar
Valentin Buck committed
13
- by downloading, using or modifying this software, you choose to accept this license ([section 10](LICENSE.md#10-Acceptance-of-the-Licence))
Valentin Buck's avatar
Valentin Buck committed
14
15
16
17
- you are free to use, reproduce and modify the work ([section 2](LICENSE.md#2-Scope-of-the-rights-granted-by-the-Licence))
- you need to keep intact all license, copyright and other attribution notices ([section 5](LICENSE.md#5-Obligations-of-the-Licensee))
- if you modify the software, you need to prominently mark it as such and provide the modified source code under this or a later version of this license ([section 5](LICENSE.md#5-Obligations-of-the-Licensee))
- you accept that we do not offer warranty for this work ([section 7](LICENSE.md#7-Disclaimer-of-Warranty)) and are not liable for damages caused by it ([section 8](LICENSE.md#8-Disclaimer-of-Liability))
Valentin Buck's avatar
Valentin Buck committed
18

Valentin Buck's avatar
Valentin Buck committed
19
A full license text can be found in the file [LICENSE.md](LICENSE.md).
Valentin Buck's avatar
Valentin Buck committed
20
21
Translations are available at https://joinup.ec.europa.eu/collection/eupl/eupl-text-eupl-12 

Valentin Buck's avatar
Valentin Buck committed
22
23
## Release and Download

24
The gitlab builds new versions of the Digital Earth Viewer daily.
Valentin Buck's avatar
Valentin Buck committed
25

26
Click on your operating system icon to download a bundled desktop executable.
Valentin Buck's avatar
Valentin Buck committed
27

28
29
30
31
[<img width="120px" src="documentation/icons/Logo-ubuntu_no_r_-black_orange-hex.svg.png">](https://git.geomar.de/digital-earth/digital-earth-viewer/-/jobs/artifacts/master/raw/tileserver/target/release/digitalearthviewer?job=build_bundled_linux)

[<img width="120px" src="documentation/icons/320px-Windows_darkblue_2012.svg.png">](https://git.geomar.de/digital-earth/digital-earth-viewer/-/jobs/artifacts/master/raw/tileserver/target/release/digitalearthviewer.exe?job=build_bundled_windows)

Valentin Buck's avatar
Valentin Buck committed
32
33
34
35
36
There are also [releases](https://git.geomar.de/digital-earth/digital-earth-viewer/-/releases) prepared every few months which contain other platform builds as well.

## Manuals

[<img width="120px" src="documentation/icons/DEV_Handbook_Icon.png">](documentation/pdf_manuals/UserManual.pdf)
Valentin Buck's avatar
Valentin Buck committed
37
38
[User Manual](documentation/pdf_manuals/UserManual.pdf)

Valentin Buck's avatar
Valentin Buck committed
39
[<img width="120px" src="documentation/icons/DEV_Difference_Layer_Icon.png">](documentation/pdf_manuals/ColorScalarLayers.pdf)
Valentin Buck's avatar
Valentin Buck committed
40
41
[Layer Recipe Cookbook](documentation/pdf_manuals/ColorScalarLayers.pdf)

Flemming Stäbler's avatar
Flemming Stäbler committed
42
[<img width="120px" src="documentation/icons/DEV_Video_Icon.png">](https://git.geomar.de/digital-earth/digital-earth-viewer/-/wikis/One-Minute-Tutorials)
Valentin Buck's avatar
Valentin Buck committed
43
[Video Tutorials](https://git.geomar.de/digital-earth/digital-earth-viewer/-/wikis/One-Minute-Tutorials)
44

Valentin Buck's avatar
Valentin Buck committed
45

46
47
## Running A Prebuilt Binary Locally
The Server hosts the website and the tiles on http://127.0.0.1:8080. It should automatically open in your default browser.
48
You can change the port using the `PORT` environment variable.
Valentin Buck's avatar
Valentin Buck committed
49

Flemming Stäbler's avatar
Flemming Stäbler committed
50
## Building The Tileserver
Flemming Stäbler's avatar
Flemming Stäbler committed
51

52
Building the tileserver takes the same steps on Windows, Linux and MacOS:
Flemming Stäbler's avatar
Flemming Stäbler committed
53
54
* [Download and install Rust](https://rustup.rs).
    * On some systems you might have to log out and log in again for the `PATH` environment variable to update after installation. You may even have to set it manually.
Flemming Stäbler's avatar
Flemming Stäbler committed
55
* Switch to the `nightly` branch. Note that some components of the rust compiler may not be available with every nightly build.
Flemming Stäbler's avatar
Flemming Stäbler committed
56
57
    * `tileserver` needs to be built with `nightly` because it uses async closures, which aren't supported in `stable` yet.
    * Switch using `$ rustup default nightly`.
Flemming Stäbler's avatar
Flemming Stäbler committed
58
* Install a C++ compiler, e.g. `msvc` on Windows or `gcc` on Linux.
Flemming Stäbler's avatar
Flemming Stäbler committed
59
60
61
62
63
    * Be careful to have an up-to-date version of the `msvc`. It is usually installed with the [Visual Studio Community Edition](https://visualstudio.microsoft.com/download) or the [Microsoft Build Tools for C++](https://visualstudio.microsoft.com/visual-cpp-build-tools/).
* Install [cmake](https://cmake.org/).
* Install [GNU M4](https://www.gnu.org/software/m4/m4.html). On Windows, it is available through [`mingw-get`](http://www.mingw.org/wiki/Getting_Started).
    * This is required to build `hdf5` for static linking.
* Build using `$ cargo build` or `$ cargo build --release` from the tileserver directory. A first-time build may take 15 minutes or more. Later builds will be faster.
Flemming Stäbler's avatar
Flemming Stäbler committed
64
    * Check out `Cargo.toml` which lists in the `[features]` section optional features that do not get compiled into the binary by default. For example, you can bundle the client into the server binary. 
65
    * Be sure to have sufficient disk space to store the build artifacts. Building both `dev` and `release` will result in several GB of build artifacts for incremental builds, even though the release binary is only 8.5 MB. Use a filesystem that supports symbolic links (not FAT32).
Valentin Buck's avatar
Valentin Buck committed
66
* Build with `--features bundled` to include the tileclient into the server binary. Otherwise you'll have to build the tileclient for development.
67

68
## Building The Tileclient For Development
Flemming Stäbler's avatar
Flemming Stäbler committed
69
70
71
72

* Install [`node`](https://nodejs.org/).
* Run `$ npm install` in the tileclient directory.

Flemming Stäbler's avatar
Flemming Stäbler committed
73
Run `$ npm run dev` in the tileclient directory to get live updates of the client during development.
74
75
76
77

This will use Vue.js development mode and allow "hot module reload". Note that HMR is unlikely to work for graphics-related code since reloading usually leads to creation of a new WebGLRenderingContext, invalidating existing textures, programs and buffers.
Changes to any of the data models may require deleting cache databases.
tileclient development files are served by the tileserver from `tileserver/dist/`, which is managed by parcel. Shaders are not managed by parcel directly, to rebuild them exit from the parcel process and restart it.
Flemming Stäbler's avatar
Flemming Stäbler committed
78
79
80
81

### Reference Documents

* [WebGL Fundamentals](https://git.geomar.de/snippets/119#webgl)
Flemming Stäbler's avatar
Flemming Stäbler committed
82
* [Renderer Implementation Details](https://git.geomar.de/snippets/120#webgl-rendering-of-4d-geodata)