Cesium Terrain Server

A basic server for serving up filesystem based tilesets representing Cesium.js terrain models. The resources served up are intended for use with the CesiumTerrainProvider JavaScript class present in the Cesium.js client.

This has specifically been created for easing the development and testing of terrain tilesets created using the Cesium Terrain Builder tools.

This project also provides a Docker container to further simplify deployment of the server and testing of tilesets. See the Docker Registry for further details.

Usage

The terrain server is a self contained binary with the following command line options:

$ cesium-terrain-server:
  -base-terrain-url="/tilesets": base url prefix under which all tilesets are served
  -cache-limit=1.00MB: the memory size in bytes beyond which resources are not cached. Other memory units can be specified by suffixing the number with kB, MB, GB or TB
  -dir=".": the root directory under which tileset directories reside
  -log-level=notice: level at which logging occurs. One of crit, err, notice, debug
  -memcached="": (optional) memcached connection string for caching tiles e.g. localhost:11211
  -no-request-log=false: do not log client requests for resources
  -port=8000: the port on which the server listens
  -web-dir="": (optional) the root directory containing static files to be served

Assume you have the following (small) terrain tileset (possibly created with ctb-tile):

/data/tilesets/terrain/srtm/
├── 0
│   └── 0
│       └── 0.terrain
├── 1
│   └── 1
│       └── 1.terrain
├── 2
│   └── 3
│       └── 3.terrain
└── 3
    └── 7
        └── 6.terrain

To serve this tileset on port 8080, you would run the following command:

cesium-terrain-server -dir /data/tilesets/terrain -port 8080

The tiles would then be available under http://localhost:8080/tilesets/srtm/ (e.g. http://localhost:8080/tilesets/srtm/0/0/0.terrain for the root tile). This URL, for instance, is what you would use when configuring CesiumTerrainProvider in the Cesium client.

Serving up additional tilesets is simply a matter of adding the tileset as a subdirectory to /data/tilesets/terrain/. For example, adding a tileset directory called lidar to that location will result in the tileset being available under http://localhost:8080/tilesets/lidar/.

Note that the -web-dir option can be used to serve up static assets on the filesystem in addition to tilesets. This makes it easy to use the server to prototype and develop web applications around the terrain data.

`layer.json`

The CesiumTerrainProvider Cesium.js class requires that a layer.json resource is present describing the terrain tileset. The ctb-tile utility does not create this file. If a layer.json file is present in the root directory of the tileset then this file will be returned by the server when the client requests it. If the file is not found then the server will return a default resource.

Root tiles

The Cesium javascript client requires that the two top level tiles representing zoom level 0 are always present. These tiles are represented by the 0/0/0.terrain and 0/1/0.terrain resources. When creating tilesets using the ctb-tile utility only one of these tiles will be generated unless the source terrain dataset intersects with the prime meridian. The terrain server addresses this issue by serving up a blank terrain tile if a top level tile is requested which does not also exist on the filesystem.

Caching tiles with Memcached

The terrain server can use a memcache server to cache tileset data. It is important to note that the terrain server does not use the cache itself, it only populates it for each request. The idea is that a reverse proxy attached to the memcache (such as Nginx) will first attempt to fulfil a request from the cache before falling back to the terrain server, which will then update the cache.

Enabling this functionality requires specifying the network address of a memcached server (including the port) using the -memcached option. E.g. A memcached server running at memcache.me.org on port 11211 can be used as follows:

cesium-terrain-server -dir /data/tilesets/terrain -memcached memcache.me.org:11211

If present, the terrain server uses the value of the custom X-Memcache-Key header as the memcache key, otherwise it uses the value of the request URI. A minimal Nginx configuration setting X-Memcache-Key is as follows:

server {
    listen 80;

    server_name localhost;

    root /var/www/app;
    index index.html;

    location /tilesets/ {
        set            $memcached_key "tiles$request_uri";
        memcached_pass memcached:11211;
        error_page     404 502 504 = @fallback;
        add_header Access-Control-Allow-Origin "*";

        location ~* \.terrain$ {
            add_header Content-Encoding gzip;
        }
    }

    location @fallback {
        proxy_pass     http://tiles:8000;
        proxy_set_header X-Memcache-Key $memcached_key;
    }
}

The -cache-limit option can be used in conjunction with the above to change the memory limit at which resources are considered to large for the cache.

Installation

The server is written in Go and requires Go to be present on the system when compiling it from source. As such, it should run everywhere that Go does. Assuming that you have set the GOPATH, installation is a matter of running go install:

go get github.com/geo-data/cesium-terrain-server/cmd/cesium-terrain-server

A program called cesium-terrain-server should then be available under your GOPATH (or GOBIN location if set).

Developing

The code has been developed on a Linux platform. After downloading the package you should be able to run make from the project root to build the server, which will be available as ./bin/cesium-terrain-server.

Executing make docker-local will create a docker image tagged geodata/cesium-terrain-server:local which when run with a bind mount to the project source directory is very handy for developing and testing.

Issues and Contributing

Please report bugs or issues using the GitHub issue tracker.

Code and documentation contributions are very welcome, either as GitHub pull requests or patches.

License

The Apache License, Version 2.0.

Contact

Homme Zwaagstra hrz@geodata.soton.ac.uk

sparksustc/cesium-terrain-server