Data sources

The Procedural GL JS library is easy to set up, but to get it working for a real-world location you will need to connect it to a source of data.

Types of data

The library requires two datasources:

• An imagery datasource, typically aerial imagery. The data format is XYZ tiles of size 256px. Data formats supported: jpeg, png & webp
• An elevation datasource. The data format is XYZ tiles of size 512px in png format

Recommended setup

The easiest way to setup the library is to use the map tiles provided by MapTiler. These tiles have been tested and work well globally with the library. To get setup:

1. Click here to sign up for an account with MapTiler
2. Obtain an API key from the MapTiler dashboard

With the Maptiler API key, you can construct the datasource definition as follows:

// Configure datasources
const datasource = {
  provider: 'maptiler',
  apiKey: MAPTILER_APIKEY
};

Provider presets

The library has some presets for compatible imagery & elevation tile providers.

Maptiler (see above for full instructions)

// Configure datasources
const datasource = {
  provider: 'maptiler',
  apiKey: MAPTILER_APIKEY
};

Mapbox

// Configure datasources
const datasource = {
  provider: 'mapbox',
  apiKey: MAPBOX_APIKEY
};

Custom datasource setup (advanced)

You can also setup any tile source for elevation and imagery data. Here we will use Maptiler & NASADEM as examples.

Imagery data

1. Click here to sign up for an account with MapTiler
2. Obtain an API key from the MapTiler dashboard

Elevation data

For elevation, nasadem.XYZ provides tiles that are compatible with the library. To get setup:

1. Click here to sign up for an account with nasadem.XYZ
2. Obtain an API key from the nasadem.XYZ dashboard

With these two API keys, you can construct the datasource definition as follows:

// Configure datasources
const datasource = {
  elevation: {
    apiKey: 'API_KEY_FROM_www.nasadem.xyz',
    attribution: '&copy;<a href="https://www.nasadem.xyz">nasadem.XYZ</a>',
    pixelEncoding: 'nasadem', // or 'terrain-rgb', 'terrarium'
    urlFormat: 'https://www.nasadem.xyz/api/v1/dem/{z}/{x}/{y}.png?key={apiKey}'
  },
  imagery: {
    apiKey: 'API_KEY_FROM_YOUR_IMAGERY_PROVIDER',
    urlFormat: 'https://api.maptiler.com/tiles/satellite/{z}/{x}/{y}.jpg?key={apiKey}',
    attribution: '<a href="https://www.maptiler.com/copyright/">Maptiler</a> <a href="https://www.openstreetmap.org/copyright">OpenStreetMap</a> contributors'
  },
};

Alternate data sources

As long as the data format and tile sizes are as described above, you can also use alternative data sources. Be sure to refer to the relevant documentation to construct the urlFormat template string and the attribution correctly.

Adjusting tile zoom level (advanced)

By default Procedural GL JS will request tiles up to zoom level 12 for elevation tiles and 18 for imagery tiles. Please note that elevation tiles are 512x512, while imagery tiles are 256x256, thus this corresponds to levels 13 & 18 in terms of level of detail.

To change the maximum zoom level requested you will need define a custom datasource, and add the maxZoom key, for example:

// Configure datasources
const datasource = {
  elevation: {
    apiKey: 'API_KEY_FROM_www.nasadem.xyz',
    attribution: '&copy;<a href="https://www.nasadem.xyz">nasadem.XYZ</a>',
    pixelEncoding: 'nasadem', // or 'terrain-rgb', 'terrarium'
    maxZoom: 9,
    urlFormat: 'https://www.nasadem.xyz/api/v1/dem/{z}/{x}/{y}.png?key={apiKey}'
  },
  imagery: {
    apiKey: 'API_KEY_FROM_YOUR_IMAGERY_PROVIDER',
    urlFormat: 'https://api.maptiler.com/tiles/satellite/{z}/{x}/{y}.jpg?key={apiKey}',
    attribution: '<a href="https://www.maptiler.com/copyright/">Maptiler</a> <a href="https://www.openstreetmap.org/copyright">OpenStreetMap</a> contributors',
    maxZoom: 15
  },
};