olcs

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:

• [Adding 3D to an existing OpenLayers map](#Adding 3D to an existing OpenLayers map)
• [Extending CesiumJS with new capabilities](#Extending CesiumJS with new capabilities)
• [Cherry-picking the pieces you need](#Cherry-picking the pieces you need)

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(false); // 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.