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

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.

Option 1: Create a bathymetry tileset with the Data Workbench

This section describes how to use the Data Workbench to generate a tileset.

Download a compressed folder of the data you'll use to create the tileset, by clicking the button below:

arrow-downDownload line-delimited GeoJSON

Extract the compressed folder you downloaded to produce three sample data files.
Navigate to the Data Manager v2 tab in the Mapbox Console and drag-and-drop all three files together into this page. This will create a single project with each file as a separate layer.
Once the files have uploaded, click the link in the notification to open the project in the Data Workbench.

Inside the Data Workbench, you can inspect the data in the table view or directly on the map and switch between each layer to understand the characteristics of the dataset like what type of data it is (points, lines, polygons) and what properties are contained within the dataset. In this example, we won’t make any changes to the underlying data so you can head directly to the Publish stage.

Press Publish in the upper right.
Scroll through the UI controls on the left and make the following changes to each source:
- undersea-features-lines:
  - Set zoom visibility to 3 - 8
  - Adjust the Allowed output setting to specify a list of attributes that will appear in the final tile. Choose name, type, discoverer, and disc_year
- undersea-features-points
  - Set zoom visibility to 3 - 8
  - Adjust the Allowed output setting to specify a list of attributes that will appear in the final tile. Choose name, type, discoverer, and disc_year
  - Press the code icon to switch to the JSON editor and paste in the following snippet after the features object.


{"tiles": { "limit": [["lowest_where_in_distance", true, 10, "name"]] }}

This reduces feature density by keeping only some features per tile based on the name attribute.

water-depth
- Set zoom visibility to 0 - 8
- Adjust the Allowed output setting to output the depth field in the tileset.
- Press the code icon to switch to the JSON editor and paste in the following snippet in the features object.


{"simplification": { "outward_only": true, "distance": 1 }}

This simplifies geometry to reduce tile size while preserving important shapes by only allowing outward-expanding simplification. Next, add the following snippet after the features object.


{
    "tiles": {
        "order": "depth",
        "union": [
          {
            "group_by": ["depth"],
            "simplification": { "distance": 4, "outward_only": false }
          }
        ]
      }
}

This merges features that share the same depth value and simplifies the resulting shapes for faster rendering at lower zooms.

Select Process tileset to publish your MTS tileset.

Option 2: Create a bathymetry tileset with the Tilesets CLI

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

Download a compressed folder of the data you'll use to create the tileset, by clicking the button below:

arrow-downDownload line-delimited GeoJSON

Extract the compressed folder you downloaded 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/v3.5.1/mapbox-gl.css" rel="stylesheet">
<script src="https://api.mapbox.com/mapbox-gl-js/v3.5.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

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`

Was this example helpful?

Why generate a multilayer tileset?​

Bathymetry data​

Option 1: Create a bathymetry tileset with the Data Workbench​

Option 2: Create a bathymetry tileset with the Tilesets CLI​

Preview your tileset​

Recipe options used​