Ol-Cesium

OpenLayers - Cesium integration library

View project on GitHub

Download release Browse examples View API docs

OpenLayers - Cesium library

OLCS is an opensource JS library for making OpenLayers and CesiumJS works together, in the same application. It addresses several use-cases:

See live examples.

The npm package is called olcs. Note that CesiumJS is accessed through the global window.Cesium object.

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 you need 2 datasets, see the customProj example.

Adding 3D to an existing OpenLayers map

// Create an OpenLayers map or start from an existing one.
import Map from 'ol/Map.js';
const ol2dMap = new Map({
    ...
});
ol2dMap.addLayer(....)

// Pass the map to the OL-Cesium constructor
// OL-Cesium will create and synchronize a 3D CesiumJs globe from your layers and data.
import OLCesium from 'olcs';
const ol3d = new OLCesium({map: ol2dMap});

ol3d.setEnabled(true); // switch to 3D - show the globe
ol3d.setEnabled(true); // switch to 2D - show the map

Build with your prefered bundler.

You can use any version of CesiumJS: latest upstream, a fork… Simply provide it as window.Cesium global:

<script src="https://cesium.com/downloads/cesiumjs/releases/1.113/Build/Cesium/Cesium.js"></script>

Extending CesiumJS with new capabilities

// Start from a CesiumJS globe
const viewer = getYourCesiumJSViewer();

// Add OpenLayers imagery provider
import {OLImageryProvider} from 'olcs';
viewer.scene.imageryLayers.addImageryProvider(new OLImageryProvider(...));

// Add Mapbox MVT imagery provider (client side rendering)
import {MVTImageryProvider} from 'olcs';
viewer.scene.imageryLayers.addImageryProvider(new MVTImageryProvider(...));

This is a bit limited at the moment but idea would be to implement:

  • client side reprojection;
  • full client side MVT rendering;
  • GeoTIFF rendering;
  • … any feature available in OpenLayers.

Cherry-picking the pieces you need

Specific low level functionnalities can be cherry-picked from the library. For example:

// GoogleMap rotating effect
import {rotateAroundBottomCenter} from 'olcs';
rotateAroundBottomCenter(viewer.scene, someAngle);

// convert OpenLayers Vector Layer to CesiumJS primitives
import {FeatureConverter} from 'olcs';
const converter = new FeatureConverter(viewer.scene);
const featurePrimitiveMap: Record<number, PrimitiveCollection> = {};
const counterpart: VectorLayerCounterpart = this.converter.olVectorLayerToCesium(olLayer, view, featurePrimitiveMap);
const csPrimitives = counterpart.getRootPrimitive();
viewer.scene.primitives.add(csPrimitives);

// Even more powerful, use a synchronizer
import {VectorSynchronizer} from 'olcs';
const synchronizer = new VectorSynchronizer(ol2dMtheap, viewer.scene);

If you think some low level features should be spotlited here, open an issue and let’s discuss it.

Configuration

Use properties to control specific aspects of OL-Cesium integration, see the PROPERTIES.MD.

Also, check the api doc.

Limitations due to OpenLayers

There are a few limitations due to decisions on

  • OpenLayers unmanaged layers are not discoverable and as a consequence not supported. Plain layers should be used instead of the synchronization managed manually. See https://github.com/openlayers/ol-cesium/issues/350.

  • OpenLayers interactions are not supported in 3d. See https://github.com/openlayers/ol-cesium/issues/655.

Contributing

See CONTRIBUTING.md.