Terrain in Mapbox Studio

Yesterday’s huge update to Mapbox Terrain all plugs into Mapbox Studio.

First thing you’ll want to is open the Layers panel of your Mapbox Studio style project and click the Change Source button. Edit the text field to include the map ID mapbox.mapbox-terrain-v2. (If your style is already using mapbox.mapbox-terrain-v1, just replace v1 with v2.)

Updating the look and feel of the hillshading required some changes to the underlying data fields. Upgrading an existing custom style project to v2 is simple - CartoCSS for the #landcover and #contour layers can remain the same, and basic shaded relief styling can now be done in just a few lines of code:

#hillshade {
  polygon-opacity: 0.1;
  [class='shadow'] { polygon-fill: #234; }
  [class='highlight'] { polygon-fill: white; }
}

The new release of v2 terrain provides hillshading polygons representing 6 levels of brightness, optimized to bring out more small details that sometimes get lost in v1. If you want to dig into the specific brightness levels, there is an additional level field containing the brightness level each polygon represents (as a percentage).

#hillshade {
  [level=94] { polygon-fill: #fff; }
  [level=90] { polygon-fill: #edc; }
  [level=89] { polygon-fill: #acb; }
  [level=78] { polygon-fill: #899; }
  [level=67] { polygon-fill: #567; }
  [level=56] { polygon-fill: #235; }
}

Representing shaded relief as vector polygons makes it easy to style a variety of ways, including with patterns and textures. For example we can generate a series of halftone image patterns using image editing software and use them with the polygon-pattern-file CartoCSS property to create a newsprint look in a style.

The elevation contours layer in v2 can be styled the same way as in v1, but we have some new options as well. Rather than being are made up of lines, the contours are a series of stacked polygons. This means you can apply colors or patterns to the terrain based on the elevation of the land. This is a new experimental feature and we’re still working out bugs for some areas, but for those places where it’s working well you’ve some great new styling options for hypsometric (elevation-based) coloring.

Check out our updated vector tile documentation and Mapbox Studio styling manual for full details on using Mapbox Terrain in your own custom map styles.