Bathymetry - multilayer tileset | Mapbox Tiling Service

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:

water-depth
undersea-features-points
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.11.0/mapbox-gl.css" rel="stylesheet">
<script src="https://api.mapbox.com/mapbox-gl-js/v2.11.0/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.

Natural Earth's Bathymetry dataset will become your water-depth layer.
GEBCO's IHO-IOC GEBCO Gazetteer of Undersea Feature Names will become your undersea-names and undersea-lines layers.

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.

Download the data you'll use to create the tileset:

Download line-delimited GeoJSON

Extract the data to produce three sample data files.
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

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 }
}
]
}
}
}
}

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"

Now you're ready to publish your tileset and start processing your data.

tilesets publish {username}.bathymetry

Preview your tileset

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.11.0/mapbox-gl.css" rel="stylesheet">
<script src="https://api.mapbox.com/mapbox-gl-js/v2.11.0/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

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