D3

d3-geo ​

Map projections are sometimes implemented as point transformations: a function that takes a given longitude lambda and latitude phi, and returns the corresponding xy position on the plane. For instance, here is the spherical Mercator projection (in radians):

js
function mercator(lambda, phi) {
  const x = lambda;
  const y = Math.log(Math.tan(Math.PI / 4 + phi / 2));
  return [x, y];
}

This is a reasonable approach if your geometry consists only of points. But what about discrete geometry such as polygons and polylines?

Discrete geometry introduces new challenges when projecting from the sphere to the plane. The edges of a spherical polygon are geodesics (segments of great circles), not straight lines. Geodesics become curves in all map projections except gnomonic, and thus accurate projection requires interpolation along each arc. D3 uses adaptive sampling inspired by Visvalingam’s line simplification method to balance accuracy and performance.

The projection of polygons and polylines must also deal with the topological differences between the sphere and the plane. Some projections require cutting geometry that crosses the antimeridian, while others require clipping geometry to a great circle. Spherical polygons also require a winding order convention to determine which side of the polygon is the inside: the exterior ring for polygons smaller than a hemisphere must be clockwise, while the exterior ring for polygons larger than a hemisphere must be anticlockwise. Interior rings representing holes must use the opposite winding order of their exterior ring.

D3 uses spherical GeoJSON to represent geographic features in JavaScript. D3 supports a wide variety of common and unusual map projections. And because D3 uses spherical geometry to represent data, you can apply any aspect to any projection by rotating geometry.

See one of:

  • Paths - generate SVG path data from GeoJSON
  • Projections - project spherical geometry to the plane
  • Streams - transform (either spherical or planar) geometry
  • Shapes - generate circles, lines, and other spherical geometry
  • Spherical math - low-level methods for spherical geometry

TIP

To convert shapefiles to GeoJSON, use shp2json, part of the shapefile package. See Command-Line Cartography for an introduction to d3-geo and related tools. See also TopoJSON, an extension of GeoJSON that is significantly more compact and encodes topology.

CAUTION

D3’s winding order convention is also used by TopoJSON and ESRI shapefiles; however, it is the opposite convention of GeoJSON’s RFC 7946. Also note that standard GeoJSON WGS84 uses planar equirectangular coordinates, not spherical coordinates, and thus may require stitching to remove antimeridian cuts.