davenquinn / cesium-vector-provider

Mapbox vector maps for the Cesium digital globe

Cesium Vector Provider

Mapbox vector tiles for the Cesium JS virtual globe.

This project contains a prototype renderer for Mapbox tiled vector maps atop the Cesium JS digital globe, based on Maplibre GL JS, a community-supported fork of Mapbox's legacy web mapping codebase.

The compiled module can be found on NPM at cesium-vector-provider. As of version 2, the module contains its own copy of Maplibre GL JS. We expect this to change in future versions.

Quick links

• Demo website for this module
• Cesium-Martini (dynamic terrain meshing from raster DEMs)
• Mars lab planetary GIS application
• Macrostrat globe prototype (Currently inoperable, April 2023)
• Syrtis-Jezero story map

Installation

This project is a relatively early demonstration and is not fully ready for production. It is based on Yarn version 3, with workspaces and "Plug'n'Play" enabled. Installation using NPM should also work, but is not well validated. Node version 16 or greater is recommended. To get up and running for development:

1. Clone the repository
2. git submodule update --init to get the requisite maplibre-gl dependency
3. yarn to install.
4. yarn run dev to run the demo application.

To integrate the already-compiled module in an application, consult this standalone example app for installation guidance.

Motivation and prior art

This module allows excellent Cesium 3D geospatial platform to consume vector maps following the flexible Mapbox style specification. Compared to the Mapbox stack alone, integration with Cesium allows use with a mature digital globe that supports high fidelity 3D rendering. It also allows integration of thematic vector maps with Cesium capabilities such as 3D tiles and point clouds.

This module is part of an effort to build a customizable, open-source "Google Earth"-style digital globe software stack that can form the basis for dynamic, high-resolution Earth science landscape visualization needs. Together with Cesium-Martini, which builds 3D terrain from tiled rasters, this module will enable 3D views atop a variety of source datasets. At Macrostrat, we hope to use this system to give context to Earth and planetary datasets.

Early versions of this module were built around the "basic renderer" fork of Mapbox GL by d1manson, with recent additions by kikitte. These modules use a custom fork of Mapbox GL v0.x that renders single-tile images from a Mapbox style and associated raster and vector data sources. Mapbox has not been interested in integrating interoperability-geared capabilities into the core library, presumably for commercial reasons (see the original request), and the version of Mapbox GL used in these libraries has subsequently become out of date.

Vector tile support within Cesium JS has been widely discussed for quite some time (see tracking issue). Other efforts to solve this problem include a standalone vector-tile Imagery Provider created by robbo1975, and a similar vector tile renderer within the awesome TerriaJS project (see discussion here). Both of these efforts work well, but they use CPU-based rendering of only the basic aspects of the vector-tile spec, and implement a separate styling approach from the Mapbox stack. This project seeks to support vector tiles with as much "drop-in" support for Mapbox approaches as is practicable.

The advent of the community-led Maplibre project has significantly improved the prospects for sustainable integration with a high-performance vector tile renderer. While this module still uses a custom fork of Maplibre GL JS, it has been brought up to date with the modern v2 series. Currently, we compile Maplibre GL's renderers and shaders into cesium-vector-provider, allowing the module to stand alone. Until our interaction with Maplibre stabilizes, this module will remain pinned to a specific version of that project. Check out the tracking issue at Maplibre GL for more information.

Current limitations and areas of future development

Note: As of version 2.0.0, many of the initial issues with this module have been resolved, or have a clear roadmap to resolution. Notably, the module no longer uses a custom fork of Maplibre GL JS. It does still use an outdated version (2.0.0.pre6) and internal APIs, though. Future updates will focus on adding label support, as well as reactivity, fidelity, and efficiency.

• Vector tile rendering currently uses a tile-based backend (separate renders are conducted for each map tile requested by Cesium). This is inefficient, yields pixelated output, and is ineffective for dynamically modifying the map (e.g., for filtering).
• Labels and other viewport-oriented content are not yet supported.
• Hillshade support is still at a "proof of concept" stage, and the hillshade renderer does not support overzooming as in the Mapbox stack, leading to visually poorer results.
• Cooperation with Cesium-Martini on caching and request management will increase efficiency of the globe view and improve configurability.
• It'd be nice to align the approaches used here with Cesium's first-party 3D Tiles stack, which is intended to fill similar use cases as Mapbox's 2D vector tiles stack.

To improve all of these aspects, it is likely that this module will seek to shift from a single Imagery Provider to a more "direct" WebGL or material-based renderer. It is also possible that maintaining an overarching Maplibre instance and caching apparatus, instead of the current per-tile approach, could enable more reactive and efficient rendering while minimizing the footprint of new code.

A basic pipeline for label rendering will lead to a "feature complete" implementation and suggest the proper structure for future efficiency and API improvements.

cesium-vector-provider's Issues

Remove MapLibre GL pin

As of version 2.0, we have successfully stripped custom extensions from Maplibre GL JS and included them in the separate maplibre-canvas-renderer module (part of this monorepo). However, we are still pinned to a specific (relatively old) version by virtue of being dependent on internal rendering details in the library. As we stabilize this library, a major goal should be solidifying the connection to the production Maplibre GL library and attempting to use its public API as much as possible.

Pass through Raster and Terrain tile layers to CesiumJS layers

Raster and terrain sources are handled well by Cesium and through extensions like davenquinn/cesium-martini. In order to simplify this library, we should just pass these layers through to the underlying mapping system, preserving layer order, transparency, etc. to the extent possible.

Labels

Right now, labels are not supported, but ideally they would be. I'm unsure to what extent this can be integrated with Cesium's own renderers for viewport-relative orientation, etc.

Are points as circles supported?

I'm currently using a MVT layer based on TerriaJs' implementation. I've customized it to support drawing points as circles. However, I would like to use your library as it is more complete than what I am using.

I'm running into an issue though. It seems that with your library, entire tiles are colored, rather than having circles drawn. Polygons seem to work just fine.

Here is my config:

    const exampleConfig = {
      showCanvas: true,
      style: {
        version: 8,
        sources: {
          layer1: {
            type: 'vector',
            tiles: [`${BASE_PATH}${BASE_API}/mvt/{z}/{x}/{y}.pbf`],
            // tiles: ['https://api.mapbox.com/v4/mapbox.82pkq93d/{z}/{x}/{y}.vector.pbf?sku=1012RMlsjWj1O&access_token=pk.eyJ1IjoiZXhhbXBsZXMiLCJhIjoiY2p0MG01MXRqMW45cjQzb2R6b2ptc3J4MSJ9.zA2W0IkI0c6KaAhJfk9bWg'],
          },
        },
        layers: [
          {
            id: 'background',
            type: 'background',
            paint: {
              'background-color': 'transparent',
            },
          },
          {
            id: 'point',
            source: 'layer1',
            'source-layer': 'casts',
            type: 'circle',
            paint: {
              'circle-color': '#11b4da',
              'circle-radius': 4,
              'circle-stroke-width': 1,
              'circle-stroke-color': '#fff',
            },
          },
        ],
      },
    };

And I am using it:

const p = new MVTImageryProvider(exampleConfig);
layers.addImageryProvider(p);

Attached is a screen shot with both my MVT layer and yours. My library is drawing yellow circles, while yours is coloring some tiles entirely teal, rather than drawing teal circles.

“Cannot find module '@macrostrat/cesium-vector-provider'” while running the demo application

Hi! I followed the instructions in the readme file, but failed to start the demo application. My environmnet is Windows 11, Chrome, vscode terminal.

1. Clone the repository using github desktop
2. git submodule update --init There was no output in the terminal, but I did find maplibre-gl in /packeges directory, along with maplibre-canvas-render, examples, and cesium-vector-provider.
3. yarn. Took me a while but eventually finished
4. yarn run dev Failed. It started on localhost, but keep logging errors like this:

(node:13732) [MODULE_NOT_FOUND] Error: debug tried to access supports-color (a peer dependency) but it isn't provided by its ancestors; this makes the require call ambiguous and unsound.
(Use `node --trace-warnings ...` to show where the warning was created)
(node:13732) [MODULE_NOT_FOUND] Error: Your application tried to access @znemz/cesium-navigation, but it isn't declared in your dependencies; this makes the require call ambiguous and unsound.
(node:13732) [MODULE_NOT_FOUND] Error: resium tried to access react-dom, but it isn't declared in its dependencies; this makes the require call ambiguous and unsound.
(node:13732) [MODULE_NOT_FOUND] Error: cesium tried to access url. While this module is usually interpreted as a Node builtin, your resolver is running inside a non-Node resolution context where such builtins are ignored. Since url isn't otherwise declared in cesium's dependencies, this makes the require call ambiguous and unsound.
(node:13732) [MODULE_NOT_FOUND] Error: markdown-it tried to access punycode. While this module is usually interpreted as a Node builtin, your resolver is running inside a non-Node resolution context where such builtins are ignored. Since punycode isn't otherwise declared in markdown-it's dependencies, this makes the require call ambiguous and unsound.

Then after a while it failed. Here is the error trace:

ERROR in ./src/main.ts 3:0-64
Module not found: Error: Can't resolve '@macrostrat/cesium-vector-provider' in 'D:\Path\to\repository\cesium-vector-provider\packages\example\src'
resolve '@macrostrat/cesium-vector-provider' in 'D:\Path\to\repository\cesium-vector-provider\packages\example\src' 
  Parsed request is a module
  using description file: D:\Path\to\repository\cesium-vector-provider\packages\example\package.json (relative path: ./src)
    Field 'browser' doesn't contain a valid alias configuration
    resolve as module
      resolved by pnp to D:\Path\to\repository\cesium-vector-provider\packages\cesium-vector-provider\
        using description file: D:\Path\to\repository\cesium-vector-provider\packages\cesium-vector-provider\package.json (relative path: .)
          using description file: D:\Path\to\repository\cesium-vector-provider\package.json (relative path: ./packages/cesium-vector-provider)
            no extension
              Field 'browser' doesn't contain a valid alias configuration
              D:\Path\to\repository\cesium-vector-provider\packages\cesium-vector-provider is not a file
            .ts
              Field 'browser' doesn't contain a valid alias configuration
              D:\Path\to\repository\cesium-vector-provider\packages\cesium-vector-provider.ts doesn't exist
            .tsx
              Field 'browser' doesn't contain a valid alias configuration
              D:\Path\to\repository\cesium-vector-provider\packages\cesium-vector-provider.tsx doesn't exist        
            .js
              Field 'browser' doesn't contain a valid alias configuration
              D:\Path\to\repository\cesium-vector-provider\packages\cesium-vector-provider.js doesn't exist
            as directory
              existing directory D:\Path\to\repository\cesium-vector-provider\packages\cesium-vector-provider       
                using description file: D:\Path\to\repository\cesium-vector-provider\packages\cesium-vector-provider\package.json (relative path: .)
                  use ./dist/module.js from module in package.json
                    using description file: D:\Path\to\repository\cesium-vector-provider\packages\cesium-vector-provider\package.json (relative path: ./dist/module.js)
                      no extension
                        Field 'browser' doesn't contain a valid alias configuration
                        D:\Path\to\repository\cesium-vector-provider\packages\cesium-vector-provider\dist\module.js doesn't exist
                      .ts
                        Field 'browser' doesn't contain a valid alias configuration
                        D:\Path\to\repository\cesium-vector-provider\packages\cesium-vector-provider\dist\module.js.ts doesn't exist
                      .tsx
                        Field 'browser' doesn't contain a valid alias configuration
                        D:\Path\to\repository\cesium-vector-provider\packages\cesium-vector-provider\dist\module.js.tsx doesn't exist
                      .js
                        Field 'browser' doesn't contain a valid alias configuration
                        D:\Path\to\repository\cesium-vector-provider\packages\cesium-vector-provider\dist\module.js.js doesn't exist
                      as directory
                        D:\Path\to\repository\cesium-vector-provider\packages\cesium-vector-provider\dist\module.js doesn't exist
                  use ./dist/main.js from main in package.json
                    using description file: D:\Path\to\repository\cesium-vector-provider\packages\cesium-vector-provider\package.json (relative path: ./dist/main.js)
                      no extension
                        Field 'browser' doesn't contain a valid alias configuration
                        D:\Path\to\repository\cesium-vector-provider\packages\cesium-vector-provider\dist\main.js doesn't exist
                      .ts
                        Field 'browser' doesn't contain a valid alias configuration
                        D:\Path\to\repository\cesium-vector-provider\packages\cesium-vector-provider\dist\main.js.ts doesn't exist
                      .tsx
                        Field 'browser' doesn't contain a valid alias configuration
                        D:\Path\to\repository\cesium-vector-provider\packages\cesium-vector-provider\dist\main.js.tsx doesn't exist
                      .js
                        Field 'browser' doesn't contain a valid alias configuration
                        D:\Path\to\repository\cesium-vector-provider\packages\cesium-vector-provider\dist\main.js.js doesn't exist
                      as directory
                        D:\Path\to\repository\cesium-vector-provider\packages\cesium-vector-provider\dist\main.js dowebpack 5.74.0 compiled with 1 error in 1767 ms

What may cause this error? How can I fix it? Thanks!

run error

step 1:
downlaod project & npm i (couldn't use yarn with some error)

step 2:
npm run dev

node Version: v14.20.0
npm Version: 6.14.17

and could you please add some Instructions for this plugin ?

How to update layer colors when clicked