Repository files navigation

OLCS is an opensource JS library for makingOpenLayers andCesiumJS 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)

Seelive examples.

The npm package is calledolcs.Note that CesiumJS is accessed through the globalwindow.Cesium object.

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.

// Create an OpenLayers map or start from an existing one.importMapfrom'ol/Map.js';constol2dMap=newMap({    ...});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.importOLCesiumfrom'olcs';constol3d=newOLCesium({map:ol2dMap});

ol3d.setEnabled(true);// switch to 3D - show the globeol3d.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 aswindow.Cesium global:

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

// Start from a CesiumJS globeconstviewer=getYourCesiumJSViewer();// Add OpenLayers imagery providerimport{OLImageryProvider}from'olcs';viewer.scene.imageryLayers.addImageryProvider(newOLImageryProvider(...));// Add Mapbox MVT imagery provider (client side rendering)import{MVTImageryProvider}from'olcs';viewer.scene.imageryLayers.addImageryProvider(newMVTImageryProvider(...));

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.

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

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

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

// Even more powerful, use a synchronizerimport{VectorSynchronizer}from'olcs';constsynchronizer=newVectorSynchronizer(ol2dMtheap,viewer.scene);

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

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

Also, check theapi doc.

There are a few limitations due to decisions on

• OpenLayers unmanaged layers are not discoverable and as a consequence notsupported. Plain layers should be used instead of the synchronization managedmanually. See#350.

• OpenLayers interactions are not supported in 3d. See#655.

SeeCONTRIBUTING.md.