ev-olcs
Version:
OpenLayers Cesium integration and plugin library
77 lines (68 loc) • 19 kB
HTML
<html class="default" lang="en"><head><meta charset="utf-8"/><meta http-equiv="x-ua-compatible" content="IE=edge"/><title>ol-cesium</title><meta name="description" content="Documentation for ol-cesium"/><meta name="viewport" content="width=device-width, initial-scale=1"/><link rel="stylesheet" href="assets/style.css"/><link rel="stylesheet" href="assets/highlight.css"/><script defer src="assets/main.js"></script><script async src="assets/icons.js" id="tsd-icons-script"></script><script async src="assets/search.js" id="tsd-search-script"></script><script async src="assets/navigation.js" id="tsd-nav-script"></script></head><body><script>document.documentElement.dataset.theme = localStorage.getItem("tsd-theme") || "os";document.body.style.display="none";setTimeout(() => app?app.showPage():document.body.style.removeProperty("display"),500)</script><header class="tsd-page-toolbar"><div class="tsd-toolbar-contents container"><div class="table-cell" id="tsd-search" data-base="."><div class="field"><label for="tsd-search-field" class="tsd-widget tsd-toolbar-icon search no-caption"><svg width="16" height="16" viewBox="0 0 16 16" fill="none"><use href="assets/icons.svg#icon-search"></use></svg></label><input type="text" id="tsd-search-field" aria-label="Search"/></div><div class="field"><div id="tsd-toolbar-links"></div></div><ul class="results"><li class="state loading">Preparing search index...</li><li class="state failure">The search index is not available</li></ul><a href="index.html" class="title">ol-cesium</a></div><div class="table-cell" id="tsd-widgets"><a href="#" class="tsd-widget tsd-toolbar-icon menu no-caption" data-toggle="menu" aria-label="Menu"><svg width="16" height="16" viewBox="0 0 16 16" fill="none"><use href="assets/icons.svg#icon-menu"></use></svg></a></div></div></header><div class="container container-main"><div class="col-content"><div class="tsd-page-title"><h1>ol-cesium</h1></div><div class="tsd-panel tsd-typography"><a id="md:openlayers---cesium-library" class="tsd-anchor"></a><h1 class="tsd-anchor-link">OpenLayers - Cesium library<a href="#md:openlayers---cesium-library" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24"><use href="assets/icons.svg#icon-anchor"></use></svg></a></h1><p>OLCS is an opensource JS library for making <a href="https://openlayers.org/" target="_blank" class="external">OpenLayers</a> and <a href="https://cesium.com/platform/cesiumjs/" target="_blank" class="external">CesiumJS</a> works together, in the same application.
It addresses several use-cases:</p>
<ul>
<li>[Adding 3D to an existing OpenLayers map](#Adding 3D to an existing OpenLayers map)</li>
<li>[Extending CesiumJS with new capabilities](#Extending CesiumJS with new capabilities)</li>
<li>[Cherry-picking the pieces you need](#Cherry-picking the pieces you need)</li>
</ul>
<p>See <a href="https://openlayers.org/ol-cesium/examples/" target="_blank" class="external">live examples</a>.</p>
<p>The npm package is called <a href="https://www.npmjs.com/package/olcs" target="_blank" class="external">olcs</a>.
Note that CesiumJS is accessed through the global <code>window.Cesium</code> object.</p>
<a id="md:features" class="tsd-anchor"></a><h2 class="tsd-anchor-link">Features<a href="#md:features" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24"><use href="assets/icons.svg#icon-anchor"></use></svg></a></h2><p>Switch smoothly between 2D and 3D and synchronize:</p>
<ul>
<li>Map context (bounding box and zoom level);</li>
<li>Raster data sources;</li>
<li>Vector data sources in 2D and 3D;</li>
<li>Map selection (selected items);</li>
<li>Animated transitions between map and globe view.</li>
</ul>
<p>The library is configurable and extensible and allows:</p>
<ul>
<li>Lazy or eager loading of Cesium</li>
<li>Limiting Cesium resource consumption (idle detection)</li>
</ul>
<p>For synchronization of maps in projections other than EPSG:4326 and EPSG:3857 you need 2 datasets, see the customProj example.</p>
<a id="md:adding-3d-to-an-existing-openlayers-map" class="tsd-anchor"></a><h2 class="tsd-anchor-link">Adding 3D to an existing OpenLayers map<a href="#md:adding-3d-to-an-existing-openlayers-map" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24"><use href="assets/icons.svg#icon-anchor"></use></svg></a></h2><pre><code class="js"><span class="hl-0">// Create an OpenLayers map or start from an existing one.</span><br/><span class="hl-1">import</span><span class="hl-2"> </span><span class="hl-3">Map</span><span class="hl-2"> </span><span class="hl-1">from</span><span class="hl-2"> </span><span class="hl-4">'ol/Map.js'</span><span class="hl-2">;</span><br/><span class="hl-5">const</span><span class="hl-2"> </span><span class="hl-6">ol2dMap</span><span class="hl-2"> = </span><span class="hl-5">new</span><span class="hl-2"> </span><span class="hl-7">Map</span><span class="hl-2">({</span><br/><span class="hl-2"> ...</span><br/><span class="hl-2">});</span><br/><span class="hl-3">ol2dMap</span><span class="hl-2">.</span><span class="hl-7">addLayer</span><span class="hl-2">(....)</span>
</code><button type="button">Copy</button></pre>
<pre><code class="js"><span class="hl-0">// Pass the map to the OL-Cesium constructor</span><br/><span class="hl-0">// OL-Cesium will create and synchronize a 3D CesiumJs globe from your layers and data.</span><br/><span class="hl-1">import</span><span class="hl-2"> </span><span class="hl-3">OLCesium</span><span class="hl-2"> </span><span class="hl-1">from</span><span class="hl-2"> </span><span class="hl-4">'olcs'</span><span class="hl-2">;</span><br/><span class="hl-5">const</span><span class="hl-2"> </span><span class="hl-6">ol3d</span><span class="hl-2"> = </span><span class="hl-5">new</span><span class="hl-2"> </span><span class="hl-7">OLCesium</span><span class="hl-2">({</span><span class="hl-3">map:</span><span class="hl-2"> </span><span class="hl-3">ol2dMap</span><span class="hl-2">});</span>
</code><button type="button">Copy</button></pre>
<pre><code class="js"><span class="hl-3">ol3d</span><span class="hl-2">.</span><span class="hl-7">setEnabled</span><span class="hl-2">(</span><span class="hl-5">true</span><span class="hl-2">); </span><span class="hl-0">// switch to 3D - show the globe</span><br/><span class="hl-3">ol3d</span><span class="hl-2">.</span><span class="hl-7">setEnabled</span><span class="hl-2">(</span><span class="hl-5">false</span><span class="hl-2">); </span><span class="hl-0">// switch to 2D - show the map</span>
</code><button type="button">Copy</button></pre>
<p>Build with your prefered bundler.</p>
<p>You can use any version of CesiumJS: latest upstream, a fork...
Simply provide it as <code>window.Cesium</code> global:</p>
<pre><code class="html"><span class="hl-8"><</span><span class="hl-9">script</span><span class="hl-10"> </span><span class="hl-11">src</span><span class="hl-10">=</span><span class="hl-12">"https://cesium.com/downloads/cesiumjs/releases/1.113/Build/Cesium/Cesium.js"</span><span class="hl-8">></</span><span class="hl-9">script</span><span class="hl-8">></span>
</code><button type="button">Copy</button></pre>
<a id="md:extending-cesiumjs-with-new-capabilities" class="tsd-anchor"></a><h2 class="tsd-anchor-link">Extending CesiumJS with new capabilities<a href="#md:extending-cesiumjs-with-new-capabilities" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24"><use href="assets/icons.svg#icon-anchor"></use></svg></a></h2><pre><code class="js"><span class="hl-0">// Start from a CesiumJS globe</span><br/><span class="hl-5">const</span><span class="hl-2"> </span><span class="hl-6">viewer</span><span class="hl-2"> = </span><span class="hl-7">getYourCesiumJSViewer</span><span class="hl-2">();</span><br/><br/><span class="hl-0">// Add OpenLayers imagery provider</span><br/><span class="hl-1">import</span><span class="hl-2"> {</span><span class="hl-3">OLImageryProvider</span><span class="hl-2">} </span><span class="hl-1">from</span><span class="hl-2"> </span><span class="hl-4">'olcs'</span><span class="hl-2">;</span><br/><span class="hl-3">viewer</span><span class="hl-2">.</span><span class="hl-3">scene</span><span class="hl-2">.</span><span class="hl-3">imageryLayers</span><span class="hl-2">.</span><span class="hl-7">addImageryProvider</span><span class="hl-2">(</span><span class="hl-5">new</span><span class="hl-2"> </span><span class="hl-7">OLImageryProvider</span><span class="hl-2">(...));</span><br/><br/><span class="hl-0">// Add Mapbox MVT imagery provider (client side rendering)</span><br/><span class="hl-1">import</span><span class="hl-2"> {</span><span class="hl-3">MVTImageryProvider</span><span class="hl-2">} </span><span class="hl-1">from</span><span class="hl-2"> </span><span class="hl-4">'olcs'</span><span class="hl-2">;</span><br/><span class="hl-3">viewer</span><span class="hl-2">.</span><span class="hl-3">scene</span><span class="hl-2">.</span><span class="hl-3">imageryLayers</span><span class="hl-2">.</span><span class="hl-7">addImageryProvider</span><span class="hl-2">(</span><span class="hl-5">new</span><span class="hl-2"> </span><span class="hl-7">MVTImageryProvider</span><span class="hl-2">(...));</span>
</code><button type="button">Copy</button></pre>
<p>This is a bit limited at the moment but idea would be to implement:</p>
<ul>
<li>client side reprojection;</li>
<li>full client side MVT rendering;</li>
<li>GeoTIFF rendering;</li>
<li>... any feature available in OpenLayers.</li>
</ul>
<a id="md:cherry-picking-the-pieces-you-need" class="tsd-anchor"></a><h2 class="tsd-anchor-link">Cherry-picking the pieces you need<a href="#md:cherry-picking-the-pieces-you-need" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24"><use href="assets/icons.svg#icon-anchor"></use></svg></a></h2><p>Specific low level functionnalities can be cherry-picked from the library.
For example:</p>
<pre><code class="js"><span class="hl-0">// GoogleMap rotating effect</span><br/><span class="hl-1">import</span><span class="hl-2"> {</span><span class="hl-3">rotateAroundBottomCenter</span><span class="hl-2">} </span><span class="hl-1">from</span><span class="hl-2"> </span><span class="hl-4">'olcs'</span><span class="hl-2">;</span><br/><span class="hl-7">rotateAroundBottomCenter</span><span class="hl-2">(</span><span class="hl-3">viewer</span><span class="hl-2">.</span><span class="hl-3">scene</span><span class="hl-2">, </span><span class="hl-3">someAngle</span><span class="hl-2">);</span>
</code><button type="button">Copy</button></pre>
<pre><code class="ts"><span class="hl-0">// convert OpenLayers Vector Layer to CesiumJS primitives</span><br/><span class="hl-1">import</span><span class="hl-2"> {</span><span class="hl-3">FeatureConverter</span><span class="hl-2">} </span><span class="hl-1">from</span><span class="hl-2"> </span><span class="hl-4">'olcs'</span><span class="hl-2">;</span><br/><span class="hl-5">const</span><span class="hl-2"> </span><span class="hl-6">converter</span><span class="hl-2"> = </span><span class="hl-5">new</span><span class="hl-2"> </span><span class="hl-7">FeatureConverter</span><span class="hl-2">(</span><span class="hl-3">viewer</span><span class="hl-2">.</span><span class="hl-3">scene</span><span class="hl-2">);</span><br/><span class="hl-5">const</span><span class="hl-2"> </span><span class="hl-6">featurePrimitiveMap</span><span class="hl-2">: </span><span class="hl-13">Record</span><span class="hl-2"><</span><span class="hl-13">number</span><span class="hl-2">, </span><span class="hl-13">PrimitiveCollection</span><span class="hl-2">> = {};</span><br/><span class="hl-5">const</span><span class="hl-2"> </span><span class="hl-6">counterpart</span><span class="hl-2">: </span><span class="hl-13">VectorLayerCounterpart</span><span class="hl-2"> = </span><span class="hl-5">this</span><span class="hl-2">.</span><span class="hl-3">converter</span><span class="hl-2">.</span><span class="hl-7">olVectorLayerToCesium</span><span class="hl-2">(</span><span class="hl-3">olLayer</span><span class="hl-2">, </span><span class="hl-3">view</span><span class="hl-2">, </span><span class="hl-3">featurePrimitiveMap</span><span class="hl-2">);</span><br/><span class="hl-5">const</span><span class="hl-2"> </span><span class="hl-6">csPrimitives</span><span class="hl-2"> = </span><span class="hl-3">counterpart</span><span class="hl-2">.</span><span class="hl-7">getRootPrimitive</span><span class="hl-2">();</span><br/><span class="hl-3">viewer</span><span class="hl-2">.</span><span class="hl-3">scene</span><span class="hl-2">.</span><span class="hl-3">primitives</span><span class="hl-2">.</span><span class="hl-7">add</span><span class="hl-2">(</span><span class="hl-3">csPrimitives</span><span class="hl-2">);</span>
</code><button type="button">Copy</button></pre>
<pre><code class="js"><span class="hl-0">// Even more powerful, use a synchronizer</span><br/><span class="hl-1">import</span><span class="hl-2"> {</span><span class="hl-3">VectorSynchronizer</span><span class="hl-2">} </span><span class="hl-1">from</span><span class="hl-2"> </span><span class="hl-4">'olcs'</span><span class="hl-2">;</span><br/><span class="hl-5">const</span><span class="hl-2"> </span><span class="hl-6">synchronizer</span><span class="hl-2"> = </span><span class="hl-5">new</span><span class="hl-2"> </span><span class="hl-7">VectorSynchronizer</span><span class="hl-2">(</span><span class="hl-3">ol2dMtheap</span><span class="hl-2">, </span><span class="hl-3">viewer</span><span class="hl-2">.</span><span class="hl-3">scene</span><span class="hl-2">);</span>
</code><button type="button">Copy</button></pre>
<p>If you think some low level features should be spotlited here, open an issue and let's discuss it.</p>
<a id="md:configuration" class="tsd-anchor"></a><h2 class="tsd-anchor-link">Configuration<a href="#md:configuration" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24"><use href="assets/icons.svg#icon-anchor"></use></svg></a></h2><p>Use properties to control specific aspects of OL-Cesium integration, see the <a href="https://github.com/openlayers/ol-cesium/blob/master/PROPERTIES.md" target="_blank" class="external">PROPERTIES.MD</a>.</p>
<p>Also, check the <a href="https://openlayers.org/ol-cesium/apidoc/" target="_blank" class="external">api doc</a>.</p>
<a id="md:limitations-due-to-openlayers" class="tsd-anchor"></a><h2 class="tsd-anchor-link">Limitations due to OpenLayers<a href="#md:limitations-due-to-openlayers" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24"><use href="assets/icons.svg#icon-anchor"></use></svg></a></h2><p>There are a few limitations due to decisions on</p>
<ul>
<li>
<p>OpenLayers unmanaged layers are not discoverable and as a consequence not
supported. Plain layers should be used instead of the synchronization managed
manually. See <a href="https://github.com/openlayers/ol-cesium/issues/350" target="_blank" class="external">https://github.com/openlayers/ol-cesium/issues/350</a>.</p>
</li>
<li>
<p>OpenLayers interactions are not supported in 3d. See <a href="https://github.com/openlayers/ol-cesium/issues/655" target="_blank" class="external">https://github.com/openlayers/ol-cesium/issues/655</a>.</p>
</li>
</ul>
<a id="md:contributing" class="tsd-anchor"></a><h2 class="tsd-anchor-link">Contributing<a href="#md:contributing" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24"><use href="assets/icons.svg#icon-anchor"></use></svg></a></h2><p>See <a href="media/CONTRIBUTING.md">CONTRIBUTING.md</a>.</p>
</div></div><div class="col-sidebar"><div class="page-menu"><div class="tsd-navigation settings"><details class="tsd-accordion"><summary class="tsd-accordion-summary"><h3><svg width="20" height="20" viewBox="0 0 24 24" fill="none"><use href="assets/icons.svg#icon-chevronDown"></use></svg>Settings</h3></summary><div class="tsd-accordion-details"><div class="tsd-filter-visibility"><span class="settings-label">Member Visibility</span><ul id="tsd-filter-options"><li class="tsd-filter-item"><label class="tsd-filter-input"><input type="checkbox" id="tsd-filter-protected" name="protected"/><svg width="32" height="32" viewBox="0 0 32 32" aria-hidden="true"><rect class="tsd-checkbox-background" width="30" height="30" x="1" y="1" rx="6" fill="none"></rect><path class="tsd-checkbox-checkmark" d="M8.35422 16.8214L13.2143 21.75L24.6458 10.25" stroke="none" stroke-width="3.5" stroke-linejoin="round" fill="none"></path></svg><span>Protected</span></label></li><li class="tsd-filter-item"><label class="tsd-filter-input"><input type="checkbox" id="tsd-filter-inherited" name="inherited" checked/><svg width="32" height="32" viewBox="0 0 32 32" aria-hidden="true"><rect class="tsd-checkbox-background" width="30" height="30" x="1" y="1" rx="6" fill="none"></rect><path class="tsd-checkbox-checkmark" d="M8.35422 16.8214L13.2143 21.75L24.6458 10.25" stroke="none" stroke-width="3.5" stroke-linejoin="round" fill="none"></path></svg><span>Inherited</span></label></li></ul></div><div class="tsd-theme-toggle"><label class="settings-label" for="tsd-theme">Theme</label><select id="tsd-theme"><option value="os">OS</option><option value="light">Light</option><option value="dark">Dark</option></select></div></div></details></div><details open class="tsd-accordion tsd-page-navigation"><summary class="tsd-accordion-summary"><h3><svg width="20" height="20" viewBox="0 0 24 24" fill="none"><use href="assets/icons.svg#icon-chevronDown"></use></svg>On This Page</h3></summary><div class="tsd-accordion-details"><a href="#md:openlayers---cesium-library"><span>Open<wbr/>Layers -<wbr/> <wbr/>Cesium library</span></a><ul><li><a href="#md:features"><span>Features</span></a></li><li><a href="#md:adding-3d-to-an-existing-openlayers-map"><span>Adding 3<wbr/>D to an existing <wbr/>Open<wbr/>Layers map</span></a></li><li><a href="#md:extending-cesiumjs-with-new-capabilities"><span>Extending <wbr/>CesiumJS with new capabilities</span></a></li><li><a href="#md:cherry-picking-the-pieces-you-need"><span>Cherry-<wbr/>picking the pieces you need</span></a></li><li><a href="#md:configuration"><span>Configuration</span></a></li><li><a href="#md:limitations-due-to-openlayers"><span>Limitations due to <wbr/>Open<wbr/>Layers</span></a></li><li><a href="#md:contributing"><span>Contributing</span></a></li></ul></div></details></div><div class="site-menu"><nav class="tsd-navigation"><a href="modules.html" class="current"><svg class="tsd-kind-icon" viewBox="0 0 24 24"><use href="assets/icons.svg#icon-1"></use></svg><span>ol-cesium</span></a><ul class="tsd-small-nested-navigation" id="tsd-nav-container" data-base="."><li>Loading...</li></ul></nav></div></div></div><footer><p class="tsd-generator">Generated using <a href="https://typedoc.org/" target="_blank">TypeDoc</a></p></footer><div class="overlay"></div></body></html>