DOCSEARCHbyAlgolia
Submit Docs

OLCS (OpenLayers-Cesium)

repository·master·Indexed 22 days ago

https://github.com/openlayers/ol-cesium

A library for seamless integration and synchronization between OpenLayers (2D) and CesiumJS (3D). It enables developers to switch between 2D and 3D views while maintaining map context, data sources, and selections. Key features include the OLCesium class for adding 3D capabilities to OpenLayers maps, imagery providers for CesiumJS, and utilities for converting OpenLayers vector layers, coordinates, and colors into CesiumJS primitives and objects.

Tokens
9.4K
Snippets
48
Records
59
Agent score
78%

What's inside ol-cesium

  1. Update distribution artifacts and publish the website

    master

    To rebuild the distribution artifacts (including the build folder, examples, and API docs) and publish them to the website, run the following command from the root of the repository:

    build/publish-website.sh
    $ build/publish-website.sh

  3. Add 3D capabilities to an existing OpenLayers map

    master

    You can integrate a 3D CesiumJS globe into an existing OpenLayers map using the OLCesium class. When initialized with an OpenLayers Map instance, OL-Cesium automatically creates and synchronizes a 3D globe from your existing layers and data. You can toggle between the 2D OpenLayers view and the 3D CesiumJS view using setEnabled().

    Prerequisites:

    • An existing OpenLayers Map instance.
    • CesiumJS must be available on the global window.Cesium object.

    Note on Projections: For synchronization in projections other than EPSG:4326 and EPSG:3857, you require two datasets (refer to the customProj example in the official documentation).

    import Map from 'ol/Map.js';
import OLCesium from 'olcs';

// 1. Create or use an existing OpenLayers map
const ol2dMap = new Map({
    // ... map options
});

// 2. Initialize OL-Cesium with the map
const ol3d = new OLCesium({map: ol2dMap});

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

  4. Understand the VectorLayerCounterpart class

    master

    The VectorLayerCounterpart class manages the conversion and lifecycle of OpenLayers vector layers into Cesium primitives. It maintains a context that tracks the projection, billboard collections, and a mapping between OpenLayers features and their corresponding Cesium Primitive or Billboard objects.

    When initializing a counterpart, it creates a rootCollection_ (a PrimitiveCollection) that contains both a BillboardCollection and a PrimitiveCollection. To render the converted layer in Cesium, you must retrieve this root collection using getRootPrimitive() and add it to your Cesium scene.

    To prevent memory leaks, call destroy() to remove all OpenLayers event listeners associated with the counterpart.

    // Conceptual usage of VectorLayerCounterpart
const counterpart = new VectorLayerCounterpart(layerProjection, cesiumScene);
const rootPrimitive = counterpart.getRootPrimitive();

// Add the root collection to the Cesium scene
cesiumScene.primitives.add(rootPrimitive);

// Later, clean up listeners
counterpart.destroy();

  6. Understand OL-Cesium limitations

    master

    When using OL-Cesium, be aware of the following constraints:

    • Unmanaged Layers: OpenLayers layers that are not managed by the OpenLayers map instance (unmanaged layers) are not discoverable and cannot be synchronized. You should use plain layers managed by the map for synchronization.
    • Interactions: OpenLayers-native interactions (like clicking or dragging) are not supported while in the 3D Cesium view.

  7. Extend CesiumJS with OpenLayers imagery providers

    master

    If you are starting from a CesiumJS Viewer instance rather than an OpenLayers map, you can add OpenLayers-based imagery providers to the Cesium scene. This allows you to use OpenLayers data sources within a native Cesium environment.

    Available providers include:

    • OLImageryProvider: For OpenLayers imagery.
    • MVTImageryProvider: For Mapbox MVT imagery (client-side rendering).
    // Start from a CesiumJS viewer
const viewer = getYourCesiumJSViewer();

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

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

  8. Use low-level OL-Cesium utility functions

    master

    OL-Cesium exports specific utility functions for common tasks, such as applying rotation effects to the Cesium scene.

    import {rotateAroundBottomCenter} from 'olcs';

// Apply a rotating effect to the Cesium scene
rotateAroundBottomCenter(viewer.scene, someAngle);

  9. Synchronize OpenLayers and CesiumJS vectors

    master

    For high-level synchronization of vector data between OpenLayers and CesiumJS, use the VectorSynchronizer. This manages the relationship between the 2D and 3D representations of vector data.

    import {VectorSynchronizer} from 'olcs';

// Synchronize an OpenLayers vector layer with a Cesium scene
const synchronizer = new VectorSynchronizer(ol2dMap, viewer.scene);

  10. Convert OpenLayers Vector Layers to CesiumJS Primitives

    master

    Use the FeatureConverter class to transform OpenLayers vector layers into CesiumJS primitives. This is useful for low-level control when you want to manually add OpenLayers vector data to a Cesium scene.

    import {FeatureConverter} from 'olcs';

// Initialize converter with the Cesium scene
const converter = new FeatureConverter(viewer.scene);
const featurePrimitiveMap: Record<number, PrimitiveCollection> = {};

// Convert the layer
const counterpart = converter.olVectorLayerToCesium(olLayer, view, featurePrimitiveMap);

// Get the root primitive and add it to the Cesium scene
const csPrimitives = counterpart.getRootPrimitive();
viewer.scene.primitives.add(csPrimitives);

  11. Configure OLCesiumOptions

    master

    The OLCesiumOptions object defines the configuration for the integration:

    PropertyTypeDescription
    mapMapThe OpenLayers map instance to synchronize with Cesium.
    targetElement or stringThe DOM element where the Cesium scene will be rendered. If omitted, it is placed over the map.
    time() => JulianDateA function that returns the current Cesium.JulianDate. Controls the Cesium clock.
    createSynchronizers(map, scene, dataSourceCollection) => AbstractSynchronizer[]A callback to provide custom synchronizers. If omitted, default raster, vector, and overlay synchronizers are used.
    stopOpenLayersEventsPropagationbooleanIf true, prevents mouse/touch events from reaching OpenLayers when Cesium is active (useful when Cesium is layered over the map).
    sceneOptionsCesium.SceneOptionsConfiguration passed directly to the Cesium.Scene constructor (excludes canvas and scene3DOnly).

  12. Enable shadows with olcs_shadows

    master

    The olcs_shadows property (boolean) enables shadow casting in the 3D view. It can be applied to an entire feature set or to individual features.

    Requirements for shadows to work:

    1. The Cesium shadowMap must be enabled in the Cesium scene.
    2. To use the sun as a light source, you must enable enableLighting on the Cesium Globe.
    // Value: boolean
feature.set('olcs_shadows', true);