On the left (or on top, on a small screen) you can see a map or a globe
that was built completely with open-source software and public-domain data.
The map is rendered in the browser with the
MapLibre GL JavaScript library, styled through MapLibre style
documents (style.json), and it only shows tiles that were created from
Natural Earth data.
Every ingredient — the vector and raster tiles, the vendored MapLibre library, the glyph fonts and even the country label sizes — is generated by a set of Makefiles in the companion repository (see Built with Make). This page and the tiles are then served by GitHub Pages from a dedicated branch of that repository.
Natural Earth is a public-domain map dataset curated by the North American Cartographic Information Society (NACIS). It is a popular starting point for cartographers because it is free of restrictions and offers clean, well-generalised data at three scales — 1:10m, 1:50m and 1:110m — split into cultural, physical and raster themes.
This site uses the 1:10m data exclusively: the country polygons come from the cultural vectors, the shaded-relief background from the Natural Earth II raster (both described below).
The country shapes are taken from the Admin 0 – Countries theme of the
1:10m cultural vectors. Every
country carries a rich set of attributes — the ISO code (ADM0_A3), its name in many languages
(NAME, NAME_DE, NAME_AR, …), the continent, even label coordinates —
which the map styles use to draw, hover and label the countries.
The polygons are converted into Mapbox Vector Tiles (MVT) — a compact binary vector format
that the browser renders on the fly — in the Web-Mercator tiling scheme from zoom 0 to 8.
The tiles are published as tiles/{z}/{x}/{y}.pbf and described by the TileJSON manifest
tiles/tiles.json, which the style file points at.
The physical Ocean theme travels in the very same tiles as a second source layer, which is what lets a style variation veil the water without a second tile source.
The basemap background is the Natural Earth II 1:10m
raster — the
LR version (light-shaded relief with water and drainages) that gives the map its
three-dimensional look, similar to OpenFreeMap's ne2_shaded background.
It is cut into 256 × 256 px Web-Mercator PNG tiles for zoom
0 to 6, published under raster/{z}/{x}/{y}.png and referenced by
style.json as the ne2_shaded raster source.
Turning the raw Natural Earth downloads into tiles is a job for a whole tool-chain of open-source utilities:
ogr2ogr
converts the shapefiles (to GeoJSON or directly to MVT), while gdal2tiles.py and
gdal_translate build the PNG raster pyramid.
tile-join utility merges them into the final tile set.
.mbtiles archive into a
folder of individual tiles, which is what a static host needs.
gdal2tiles.py and small helper scripts.sqlite3) — reads the metadata of the .mbtiles archives.
The companion repository contains one self-contained Makefile per module (under
make/); the root Makefile is a small dispatcher that forwards
make <module> to the right module. Each module downloads its source and builds one
deployable ingredient:
| module | command | output | source |
|---|---|---|---|
| vector MVT tiles |
make vector |
tiles/{z}/{x}/{y}.pbf, z0–8 |
Natural Earth 1:10m admin-0 countries |
| raster PNG tiles |
make raster |
raster/{z}/{x}/{y}.png, z0–6 |
Natural Earth II 1:10m LR shaded relief |
| maplibre-gl vendored JS |
make maplibre-gl |
js/ + css/ |
the maplibre-gl npm package |
| font glyph PBFs |
make font |
font/<stack>/<range>.pbf |
Google Noto Sans (via fontnik) |
| country-sizes label sizes |
make country-sizes |
country-sizes.json |
the vector module's countries.geojson |
Run make for the dispatcher help, make all to build everything, or
make check to verify the tools each module needs. Builds are incremental; downloads and
intermediate files are cached in gitignored folders (.vector-src/, .raster-src/,
.font-src/, .font-tools/). Module variables pass through, e.g.
make vector MAX_ZOOM=6 or make raster RASTER_MAX_ZOOM=4.
MapLibre renders text from glyph PBFs — pre-built font ranges in a protobuf format. They are
generated with fontnik from the
Noto Sans family on
Google Fonts (Regular and Bold, plus Arabic and Hebrew variants) and
published as font/<Font Stack>/<range>.pbf. The styles reference them through the
glyphs URL template font/{fontstack}/{range}.pbf.
Only the Latin script is rendered for the time being, so the style asks for the single font stack
["Noto Sans Regular"] — a static host cannot merge glyphs across separate font folders.
We created a branch gh-pages and pushed the tiles/ folder as well as this little
demo website (html/js/css) to the
natural-earth-tiles repository. Everything else
is done by GitHub, which serves the files from this repository as a static website at
https://matths.github.io/natural-earth-tiles/.
From there one can access the tiles via their TileJSON manifest,
tiles/tiles.json, and the map's look via
style.json.
One subtlety: static hosts such as GitHub Pages serve .pbf files without a
Content-Encoding: gzip header, so the vector tiles are stored as raw (uncompressed)
MVT — the Makefiles take care of that.
MapLibre GL renders the same tiles both as a classic Web-Mercator map and as a
3D globe. style.json starts in the globe projection and the page
zooms the globe as large as the frame allows, and a control on the map switches between the flat map and
the globe while you interact.
This website was created by Matthias Dittgen (@matths), but couldn't be done without some people answering my questions on the OSM Slack (OpenStreetMap) — especially Daniel Schep (@dschep), Andy Townsend and Andrew Calcutt (@acalcutt).