All docschevron-rightMapbox Tiling Servicechevron-rightarrow-leftExampleschevron-rightBathymetry - multilayer tileset

Bathymetry - multilayer tileset

Tilesets can contain multiple layers. This is especially useful when you have multiple, but related, geographical datasets that will be used together in a style. mapbox-public.bathymetry is a multilayer tileset that includes 3 related layers:

  1. water-depth
  2. undersea-features-points
  3. undersea-features-lines

These are all bathymetric data, but each layer is a distinct kind of information.

<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8">
<title>Bathymetry - multilayer tileset</title>
<meta name="viewport" content="initial-scale=1,maximum-scale=1,user-scalable=no">
<link href="https://api.mapbox.com/mapbox-gl-js/v2.14.1/mapbox-gl.css" rel="stylesheet">
<script src="https://api.mapbox.com/mapbox-gl-js/v2.14.1/mapbox-gl.js"></script>
<style>
body { margin: 0; padding: 0; }
#map { position: absolute; top: 0; bottom: 0; width: 100%; }
</style>
</head>
<body>
<div id="map"></div>
<script>
// TO MAKE THE MAP APPEAR YOU MUST
// ADD YOUR ACCESS TOKEN FROM
// https://account.mapbox.com
mapboxgl.accessToken = 'YOUR_MAPBOX_ACCESS_TOKEN';
const map = new mapboxgl.Map({
container: 'map',
style: 'mapbox://styles/examples/ckoyugkr906bd17o6jv7732xa',
zoom: 3,
center: [122.473, 0.4182]
});
</script>
</body>
</html>

Why generate a multilayer tileset?

Compared to the process of generating and managing a single tileset for each collection of data, a multilayer tileset keeps related data together, making them simpler to create, update, and manage. For information about when a multilayer tileset is appropriate, see the Multilayer tilesets troubleshooting guide.

A multilayer recipe includes multiple keys in the layers element. Each unique key generates a layer and has the same layer configuration options available in a single layer recipe.

Bathymetry data

You will generate a multilayer tileset using data from Natural Earth and GEBCO.

This recipe excerpt shows how to include multiple layer elements to produce a multilayer tileset. Each layer has a unique name and typically has its own data source.

{
"version": 1,
"layers": {
"water-depth": {
"source": "mapbox://tileset-source/{username}/water-detail",
// layer configuration
},
"undersea-features-points": {
"source": "mapbox://tileset-source/{username}/undersea-names",
// layer configuration
},
"undersea-features-lines": {
"source": "mapbox://tileset-source/{username}/undersea-lines",
// layer configuration
}
}
}

The map on the left is a single layer tileset generated without any tiles or features options in its recipe. The map on the right is a multilayer tileset with the recipe configurations outlined below.

Create a bathymetry tileset with the Tilesets CLI

This section describes how to use the Tilesets CLI to generate a tileset.

  1. Download the data you'll use to create the tileset:
arrow-downDownload line-delimited GeoJSON
  1. Extract the data to produce three sample data files.

  2. Using the Tilesets CLI, create a tileset source for each of the data files. Give each source a unique name. Replace {username} with your Mapbox username.

tilesets upload-source {username} undersea-lines ~/your/local/path/undersea-lines.geojson
tilesets upload-source {username} undersea-names ~/your/local/path/undersea-names.ldgeojson
tilesets upload-source {username} water-detail ~/your/local/path/water-detail.ldgeojson
  1. Create your recipe as a local JSON file (such as bathymetry-recipe.json) with your undersea-lines, undersea-names, and water-detail tileset sources.
{
"version": 1,
"layers": {
"undersea-features-lines": {
"source": "mapbox://tileset-source/{username}/undersea-lines",
"minzoom": 3,
"maxzoom": 8,
"features": {
"attributes": {
"allowed_output": ["name", "type", "discoverer", "disc_year"]
}
}
},
"undersea-features-points": {
"source": "mapbox://tileset-source/{username}/undersea-names",
"minzoom": 3,
"maxzoom": 8,
"features": {
"attributes": {
"allowed_output": ["name", "type", "discoverer", "disc_year"]
}
},
"tiles": { "limit": [["lowest_where_in_distance", true, 10, "name"]] }
},
"water-depth": {
"source": "mapbox://tileset-source/{username}/water-detail",
"minzoom": 0,
"maxzoom": 8,
"features": {
"attributes": { "allowed_output": ["depth"] },
"simplification": { "outward_only": true, "distance": 1 }
},
"tiles": {
"order": "depth",
"union": [
{
"group_by": ["depth"],
"simplification": { "distance": 4, "outward_only": false }
}
]
}
}
}
}
  1. Create a tileset with the ID {username}.bathymetry using your recipe and name it "bathymetry multilayer". This tileset will be empty until you publish it.
tilesets create {username}.bathymetry --recipe ~/your/local/path/bathymetry-recipe.json --name "bathymetry multilayer"
  1. Now you're ready to publish your tileset and start processing your data.
tilesets publish {username}.bathymetry

Preview your tileset

  1. You can now add your new tileset to a map style to visualize its data. Below is an example of how to add the {username}.bathymetry tileset as a vector tile source to a Mapbox GL JS map style. Add each of your tileset's layers to the map as separate style layers that can be styled individually.
<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8">
<title>Bathymetry - multilayer tileset</title>
<meta name="viewport" content="initial-scale=1,maximum-scale=1,user-scalable=no">
<link href="https://api.mapbox.com/mapbox-gl-js/v2.14.1/mapbox-gl.css" rel="stylesheet">
<script src="https://api.mapbox.com/mapbox-gl-js/v2.14.1/mapbox-gl.js"></script>
<style>
body { margin: 0; padding: 0; }
#map { position: absolute; top: 0; bottom: 0; width: 100%; }
</style>
</head>
<body>
<div id="map"></div>
<script>
// TO MAKE THE MAP APPEAR YOU MUST
// ADD YOUR ACCESS TOKEN FROM
// https://account.mapbox.com
mapboxgl.accessToken = 'YOUR_MAPBOX_ACCESS_TOKEN';
const map = new mapboxgl.Map({
container: 'map',
style: 'mapbox://styles/mapbox/light-v10',
zoom: 3,
center: [-13, -25]
});
map.on('load', () => {
map.addSource('bathymetry', {
type: 'vector',
url: 'mapbox://examples.bathymetry'
});
map.addLayer({
'id': 'water-depth',
'type': 'line',
'source': 'bathymetry',
'source-layer': 'water-depth',
'layout': {
'line-join': 'round',
'line-cap': 'round'
},
'paint': {
'line-color': '#69b4ff',
'line-width': 1
}
});
map.addLayer({
'id': 'undersea-features-lines',
'type': 'line',
'source': 'bathymetry',
'source-layer': 'undersea-features-lines',
'layout': {
'line-join': 'round',
'line-cap': 'round'
},
'paint': {
'line-color': '#ff69b4',
'line-width': 2
}
});
map.addLayer({
'id': 'undersea-features-points',
'type': 'circle',
'source': 'bathymetry',
'source-layer': 'undersea-features-points',
'paint': {
'circle-radius': 4,
'circle-color': '#01fe01'
}
});
map.addLayer({
'id': 'undersea-features-points-label',
'type': 'symbol',
'source': 'bathymetry',
'source-layer': 'undersea-features-points',
'layout': {
'text-field': '{name}',
'text-anchor': 'top-left',
'text-size': 12
}
});
});
</script>
</body>
</html>

Recipe options used

FieldDescriptionData type
layersThe names of the layers and their configuration options. Each layer has its own configuration.String
sourceThe source data to use for this layer. Tileset sources are created with the Create a tileset source endpoint of Mapbox Tiling Service (MTS).String