MapLibre V2: Add 3D terrain to your map

The second generation of MapLibre GL JS is here! It has been rewritten in TypeScript and maps can be displayed in 3D. All previous apps, styles, and custom maps continue to work and are now 3D-ready.

Add 3D with one simple line of code using the MapTiler SDK: See how easy adding 3D can be! The MapTiler SDK extends the functionality of MapLibre and provides an even more user-friendly experience for MapTiler Cloud maps.

What is MapLibre GL JS

MapLibre GL JS is a JavaScript library that uses WebGL to render interactive maps from vector tiles and MapLibre styles. It is part of the MapLibre GL ecosystem.

To learn more about MapLibre check out the article MapLibre: Mapbox GL open-source fork

What is new in MapLibre 2 - 3D Maps & TypeScript

3D Maps

Every map feature works seamlessly with the new 3D terrain option: existing layer types are automatically adjusted and aligned with terrain, and markers clamp to the ground.

Now you can visualize the elevation of the terrain from a DEM (RGBA tiles) including drawing the tracks, labels, and points.

To render a 3D terrain, MapLibre creates a triangle mesh, a set of 3D triangles representing the surface. This mesh is created from the terrain data coming from the DEM (RGBA tiles).

By default, the maps are 2D, but you now have the ability to view your maps in 3D. To activate the 3D option, you have to add a “raster-dem” source that contains the terrain elevations (RGBA tiles) to the map.

map.addSource("some id", {
  "type": "raster-dem",
  "url": "https://api.maptiler.com/tiles/terrain-rgb/tiles.json?key=YOUR_API_KEY",
});

Then you must enable the 3D terrain of the map indicating the data source:

map.setTerrain({
  source: "some id"
});

In the terrain options, in addition to the source, the exaggeration and elevationOffset can be indicated.

exaggeration: multiplicator for the elevation. Used to make the terrain more “extreme”. Default 1.0

Here is a code example to add terrain with an exaggeration of 2.5x to a map:

map.on('load', () => {
  map.addSource("terrain", {
    "type": "raster-dem",
    "url": "https://api.maptiler.com/tiles/terrain-rgb/tiles.json?key=YOUR_API_KEY",
  });
  map.setTerrain({
    source: "terrain",
    exaggeration: 2.5
  });
});

View complete source code on GitHub

Check out the step-by-step tutorial about How to build a 3D map with MapLibre v2.0 GL JS. You will learn how to create your first 3D map.

TypeScript

The entire library has been rewritten into TypeScript.

The source code quality of the entire MapLibre GL JS has now improved. Thanks to types, developers have fixed several bugs and improved the tests which are now more robust. This makes the code easier to maintain and helps new developers contribute.

The best news for developers is that the deprecated code has been removed while everything remains compatible at the API level. There is no need for you to change anything if you use the MapLibre JavaScript APIs or existing bindings.

If you develop large applications in TypeScript yourself and compile them together with MapLibre - you can benefit from defined types present directly in the library - instead of external @types/maplibre-gl. In this case, you should upgrade your code. This approach can also bring benefits in code reduction via tree shaking in the future.

Features and improvements

Add 3D terrain capabilities.
Now you can tilt the map over 60 degrees. Add support for unlocked pitch up to 85° (previously 60°). 60 is the default maximum value. If you want to use a higher value you must set the maxPitch property of the map. Example: maxPitch: 85.
Add option viewport-glyph to text-rotation-alignment which places glyphs along a linestring and rotates them to the x-axis of the viewport.
Default compact attribution to be open by default to comply with OpenStreetMap Attribution Guidelines.
Added redraw function to map.
Cancel pending GeoJSON requests when GeoJSONSource.setData() is called instead of waiting for any pending request to complete before issuing the request for the new URL.

Breaking changes

Migration to Typescript (some typescript typings have changed).
Removed all code related to accessToken and Mapbox specific URLs starting with mapbox://. Telemetry and tracking code were removed.
Removed baseApiUrl as it was used only for Mapbox related URLs.
Removed version from the public API
Deprecated Internet Explorer is no longer supported from this release.
Stopped supporting Chrome 49-65. Chrome 66+ is now required. For Chrome 49-65 support use version 1.15.2.

See all the changes in the new version in the CHANGELOG

The MapLibre community

All these changes and improvements were possible thanks to the effort and collaboration of the community. Special thanks to @prozessor13 for adding the option to make 3D maps and to @wipfli, @HarelM, @acalcutt, @vanilla-lake, and @rendrom among others for their contributions.

The community decided to create the MapLibre project to avoid community fragmentation and to join efforts in development and maintenance. Read the story and technical details at MapLibre: Mapbox GL open-source fork - MapTiler

MapTiler has been involved in the project from the beginning; as part of the steering committee, contributing to the website, creating documentation, maintaining the SDK, etc.

To find out more, visit the community page.