Skip to content

MapLibre renderer

Choose View → Rendering engine → MapLibre to use GeoLibre's default renderer. MapLibre GL JS is bundled with every GeoLibre distribution, requires no account or access token, and is available for both the primary map and every split pane.

MapLibre has the broadest feature and plugin compatibility in GeoLibre. New projects use it unless primaryRenderer says otherwise, and an omitted viewKind in a secondary pane also means MapLibre.

Supported paths

  • GeoJSON and imported vector data with single, categorized, graduated, rule-based, expression, proportional, heatmap, cluster, pattern, label, and extrusion styling.
  • Raster and image sources, including XYZ, WMS, WMTS, COG/GeoTIFF, image and video overlays, raster PMTiles, and desktop MBTiles.
  • Vector tiles and vector PMTiles or MBTiles, including imported Mapbox styles and ArcGIS vector-tile services.
  • 3D Tiles, I3S, LiDAR and COPC point clouds, Gaussian splats, 3D models, Zarr, NetCDF/HDF, and deck.gl visualization layers through GeoLibre's specialized renderers and overlays.
  • Feature picking, selection, editing, measurement, extent drawing, draggable placement, print and screenshot capture, and the full MapLibre-oriented plugin surface.

See Supported Data Formats and Features for the complete user-facing lists. Individual data sources can still have platform, credential, or network requirements even though the MapLibre engine itself does not.

Map, globe, and terrain

MapLibre supports Mercator and globe projections. Controls → Globe switches the projection, while Controls → Terrain adds elevation to either view. The terrain source can be GeoLibre's global source or a compatible local or remote COG DEM. This globe projection remains a MapLibre style map; choose the Cesium renderer for a native 3D globe and Cesium-native scene formats.

Other coordinate reference systems

MapLibre GL JS 6.15 can draw a flat map in any planar CRS (issue #1128). Settings → Map → Map coordinate reference system picks one, saved as preferences.map.mapCrs; absent means the default Web Mercator map or globe. The presets are polar stereographic and simple-cylindrical grids of Earth, the Moon and Mars, and simple-cylindrical grids of Mercury, Venus, Io, Europa, Ganymede, Callisto, Titan, Pluto and Charon. Each comes with a basemap the server renders in that grid: NASA GIBS for Earth and USGS Astrogeology for the other bodies, read directly rather than reprojected to Web Mercator. Picking a preset also sets the celestial body, so measurements use its radius. Custom EPSG code… takes any code the bundled EPSG tables resolve; it has no basemap, and its tile grid is fitted to the part of the world it maps.

MapLibre places tiles on the CRS's grid without reprojecting them, so in another CRS:

  • GeoJSON layers are drawn, projected by proj4 in MapLibre's workers.
  • WMS layers and ArcGIS export layers ask for each tile's box in the CRS (WMS 1.1.1, SRS=<code>). The server must support that CRS. Planetary presets ask under the labels servers read rather than their IAU code: EPSG:4326 for a simple-cylindrical grid, and the EPSG:32661/EPSG:32761 labels USGS Astrogeology serves its polar grids under.
  • Image and video overlays are drawn from their corner coordinates.
  • XYZ, vector tile, MBTiles and Wayback layers are not drawn, nor is the shared basemap, since their tiles are Web Mercator. Plugins that add their own tiles or deck.gl overlays are not adapted either; they can read the CRS, and be told when it changes, through getMapCrs and onMapCrsChange (see Reading the map CRS).
  • The globe button is hidden, terrain is off, and the restricted-bounds setting is set aside (MapLibre keeps the view inside the CRS).

Switching CRS rebuilds the style and frames the new map's area; opening a project keeps its saved view.

A link can name the CRS with crs=EPSG:32632 or a preset id, and the web address keeps it up to date, so a copied link opens the same map (see Embedding & Sharing). A plugin can switch it with setMapCrs.

Basemaps and plugins

The shared Basemaps panel provides keyless styles as well as optional provider styles configured through Settings → Environment Variables. Provider keys belong to those services and are not a requirement of MapLibre itself.

Plugins default to MapLibre support when their manifest omits engines. MapLibre-specific plugins can access the native map through app.getMap(); portable plugins should instead use the renderer-neutral or shared Style-Spec APIs described in the Plugin API.

Architecture and license

MapController is the MapLibre implementation of MapEngine. packages/map/src/layer-sync.ts reconciles project layer records with native sources and style layers, while specialized controls register protocols or shared overlays for formats that MapLibre does not draw directly. The reusable headless surface is published as @geolibre/map.

MapLibre GL JS and GeoLibre are open source under permissive licenses. See the architecture for the shared engine model and Acknowledgements for project and license links.