27 chapters
Why map math matters
What this guide covers, the notation we'll use, and why understanding map math matters even when libraries hide it.
The shape of the Earth
Sphere, ellipsoid, geoid — three models, three answers, and which one you actually need for app development.
Coordinate systems: latitude and longitude
Latitude and longitude explained — decimal vs DMS notation, WGS84 and EPSG:4326, datum shifts, and how big a degree actually is in metres.
Map projections — flattening the globe
Why every flat map lies, the math behind Web Mercator and equal-area projections, and how to pick the right projection for your use case.
Web Mercator and tile math
How every web map (Google, OSM, Mapbox) tiles the world, with the formulas to convert lat/lon to tile coordinates.
Pixel and world coordinates
World pixels and screen pixels: the coordinate system behind every marker, overlay, and mouse-to-lat-lon conversion at any zoom level.
Distance on a sphere — Haversine and friends
Why Pythagoras lies on a sphere, the full Haversine derivation, Vincenty for ellipsoid accuracy, and which formula to use for which job.
Bearings, headings, and azimuths
Computing the angle from one point to another, normalizing to compass headings, and why bearings change along a path.
Destination points — moving on a sphere
Given a starting point, bearing, and distance, compute the destination on a sphere — used for geofences, range rings, and dead reckoning.
Bounding boxes and spatial queries
How to compute a bbox from a point and radius for fast database queries — and the edge cases nobody warns you about.
Polygons — area, centroid, and containment
Ray-casting point-in-polygon, planar and spherical polygon area, centroid computation, and the edge cases every implementation misses.
Spatial indexing — Geohash, Quadtrees, S2, H3
Geohash, Quadtrees, S2, and H3 compared — how to answer 'what's near here?' across millions of points in milliseconds, and which to pick.
Map clustering algorithms
Grid clustering, distance-based methods, and the Supercluster KD-tree algorithm Mapbox and MapLibre use to cluster millions of markers.
Advanced topics — Vincenty, ECEF, and affine transforms
Sub-meter ellipsoidal accuracy with Vincenty, 3D Earth-Centered coordinates, pan/zoom transforms, and rhumb lines.
Practice problem set
Eight worked exercises with full step-by-step solutions, covering coordinate conversions, Haversine distance, tile math, and spherical area.
The antimeridian — the bug that breaks every map
Why lines and polygons that cross the ±180° longitude line break naive code, the splitting algorithm that fixes it, and GeoJSON specifics.
GeoJSON — the universal format
Every GeoJSON geometry type, winding order rules, the lon/lat ordering trap, and the validation rules that every developer trips over.
Coordinate transforms — converting between CRS
EPSG:4326 ↔ 3857 by hand, using proj4js, and the practical situations where you need to transform coordinates.
How maps render — tiles, vectors, and the GPU pipeline
From lat/lon to pixels on screen — the full rendering pipeline for raster tiles, vector tiles, and WebGL-based maps like MapLibre and Mapbox.
Geometry simplification
Douglas-Peucker and Visvalingam-Whyatt — how to strip vertices from polygons and lines without losing their shape.
Buffering and spatial operations
Expanding geometries by a distance, computing unions and intersections, and building spatial pipelines with Turf.js.
Routing on road networks
Graph representation of road networks, Dijkstra's algorithm, A* with a Haversine heuristic, and how turn restrictions change the model.
Interpolation and heat maps
Turning sparse sample points into continuous surfaces — IDW, kernel density, Kriging, and rendering techniques.
Terrain and elevation data
Digital Elevation Models, Terrain RGB encoding, hillshading math, slope and aspect — the foundation of 3D maps.
Camera and perspective math
The map camera model, pitch and bearing, perspective projection matrices, view frustum, and unprojecting pixels to world coordinates.
3D buildings and feature extrusion
Turning 2D building footprints into 3D meshes with Mapbox fill-extrusion, LOD strategies, rendering order, and the math behind extrusion.
ECEF and 3D coordinate systems
Earth-Centered Earth-Fixed coordinates, converting lat/lon/altitude to XYZ, the ENU local frame, and 3D distances.