Ol-Cesium

OpenLayers - Cesium integration library. Create your map using OpenLayers, and visualize it on a globe with Cesium. See live examples.

ES6 modules

Work is in progress to switch to ES6 modules. See alpha version package https://www.npmjs.com/package/olcs. That package is expected to be used with OpenLayers ES6 package https://www.npmjs.com/package/ol.

Features

Switch smoothly between 2D and 3D and synchronize:

Map context (bounding box and zoom level);
Raster data sources;
Vector data sources in 2D and 3D;
Map selection (selected items);
Animated transitions between map and globe view.

The library is configurable and extensible and allows:

Lazy or eager loading of Cesium
Limiting Cesium resource consumption (idle detection)

For synchronization of maps in projections other than EPSG:4326 and EPSG:3857, see #562 branch.

Getting started

To obtain Ol-Cesium, either download a release, or clone the repository and build it yourself (see below).

Applications using Ol-Cesium also need to load OpenLayers styles and Cesium resources (included in the distribution):

<link rel="stylesheet" href="ol.css" type="text/css">
<script src="Cesium/Cesium.js"></script>
<script src="olcesium.js"></script>

An OpenLayers map can be switched to a 3d globe view by running the code below after the map has been created:

var ol3d = new olcs.OLCesium({map: map}); // map is the ol.Map instance
ol3d.setEnabled(true);

The above will use the WGS84 ellipsoid all around the globe. To use terrain, simply add a terrain provider using the Cesium API (can be your own, but in the snippet below it's one that ships with Cesium):

var ol3d = new olcs.OLCesium({map: map}); // map is the ol.Map instance
var scene = ol3d.getCesiumScene();
scene.terrainProvider = new Cesium.CesiumTerrainProvider({
  url: 'https://assets.agi.com/stk-terrain/world'
});
ol3d.setEnabled(true);

Building the library

Requirements for building Ol-Cesium:

To get started, clone the Ol-Cesium repository with its submodules:

$ git clone --recursive https://github.com/openlayers/ol-cesium.git

Change into the clone directory, and invoke

$ make dist

from the root of the repository. You will then be able to use dist/olcesium.js for your applications.

Running the examples in debug mode

This is useful for contributing to Ol-Cesium, because it loads the source files instead of a minified build:

$ make serve

will make the distribution examples available at http://localhost:4000/examples

Running the unminified version of Cesium

Passing the parameter ?mode=dev to an example will load the debug version of Cesium instead of the minified one. This is helpful when something breaks inside Cesium. In distribution mode, an unminified version of OpenLayers and Ol-Cesium is also loaded.

Limitations

OpenLayers unmanaged layers are not discoverable and as a consequence not supported. Plain layers should be used instead or the synchronization managed manually. See openlayers#350.

Release process

See RELEASE.md.

dybky / ol-cesium