Geo Projections

Wiki ▸ API Reference ▸ Geo ▸ Geo Projections

D3 includes several common projections by default, as shown below. Numerous (less-commonly used) projections are available in the extended geographic projections plugin and the polyhedral projection plugin.

d3.geo.albersUsa	d3.geo.azimuthalEqualArea	d3.geo.azimuthalEquidistant
d3.geo.conicEqualArea	d3.geo.conicConformal	d3.geo.conicEquidistant
d3.geo.equirectangular	d3.geo.gnomonic	d3.geo.mercator
d3.geo.orthographic	d3.geo.stereographic	d3.geo.transverseMercator

Standard Abstract Projection

Most projections provided by D3 are created via d3.geo.projection and are configurable: you can rotate the globe, scale or transform the canvas, etc. Unless you’re implementing a new raw projection, you probably won’t use the d3.geo.projection constructor, but you are likely to use the configuration methods.

# d3.geo.projection(raw)

Constructs a new projection from the specified raw point projection function. For example, a Mercator projection can be implemented as:

var mercator = d3.geo.projection(function(λ, φ) {
  return [
    λ,
    Math.log(Math.tan(π / 4 + φ / 2))
  ];
});

(See src/geo/mercator.js for the full implementation.) If the raw function supports an invert method, then the returned projection will expose a corresponding invert method.

# projection(location)

Projects forward from spherical coordinates (in degrees) to Cartesian coordinates (in pixels). Returns an array [x, y] given the input array [longitude, latitude]. May return null if the specified location has no defined projected position, such as when the location is outside the clipping bounds of the projection.

# projection.invert(point)

Projects backward from Cartesian coordinates (in pixels) to spherical coordinates (in degrees). Returns an array [longitude, latitude] given the input array [x, y]. Not all projections implement invert; for noninvertible projections, this method is undefined.

# projection.rotate([rotation])

If rotation is specified, sets the projection’s three-axis rotation to the specified angles λ, φ and γ (yaw, pitch and roll, or equivalently longitude, latitude and roll) in degrees and returns the projection. If rotation is not specified, returns the current rotation which defaults [0, 0, 0]. If the specified rotation has only two values, rather than three, the roll is assumed to be 0°.

# projection.center([location])

If location is specified, sets the projection’s center to the specified location, a two-element array of longitude and latitude in degrees and returns the projection. If center is not specified, returns the current center which defaults to ⟨0°,0°⟩.

# projection.translate([point])

If point is specified, sets the projection’s translation offset to the specified two-element array [x, y] and returns the projection. If point is not specified, returns the current translation offset which defaults to [480, 250]. The translation offset determines the pixel coordinates of the projection’s center. The default translation offset places ⟨0°,0°⟩ at the center of a 960×500 area.

# projection.scale([scale])

If scale is specified, sets the projection’s scale factor to the specified value and returns the projection. If scale is not specified, returns the current scale factor which defaults to 150. The scale factor corresponds linearly to the distance between projected points. However, scale factors are not consistent across projections.

# projection.clipAngle(angle)

If angle is specified, sets the projection’s clipping circle radius to the specified angle in degrees and returns the projection. If angle is null, switches to antimeridian cutting rather than small-circle clipping. If angle is not specified, returns the current clip angle which defaults to null. Small-circle clipping is independent of viewport clipping via clipExtent.

# projection.clipExtent(extent)

If extent is specified, sets the projection’s viewport clip extent to the specified bounds in pixels and returns the projection. The extent bounds are specified as an array [[x0, y0], [x1, y1]], where x0 is the left-side of the viewport, y0 is the top, x1 is the right and y1 is the bottom. If extent is null, no viewport clipping is performed. If extent is not specified, returns the current viewport clip extent which defaults to null. Viewport clipping is independent of small-circle clipping via clipAngle.

# projection.precision(precision)

If precision is specified, sets the threshold for the projection’s adaptive resampling to the specified value in pixels and returns the projection. This value corresponds to the Douglas–Peucker distance. If precision is not specified, returns the projection’s current resampling precision which defaults to Math.SQRT(1/2).

A precision of 0 disables adaptive resampling.

# projection.stream(listener)

Returns a projecting stream wrapper for the specified listener. Any geometry streamed to the wrapper is projected before being streamed to the wrapped listener. A typical projection involves several stream transformations: the input geometry is first converted to radians, rotated on three axes, clipped to the small circle or cut along the antimeridian, and lastly projected to the Cartesian plane with adaptive resampling, scale and translation.

# d3.geo.projectionMutator(rawFactory)

Constructs a new projection from the specified raw point projection function factory. This function does not return the projection directly, but instead returns a mutate method that you can call whenever the raw projection function changes. For example, say you’re implementing the Albers equal-area conic projection, which requires configuring the projection's two parallels. Using closures, you can implement the raw projection as follows:

// φ0 and φ1 are the two parallels
function albersRaw(φ0, φ1) {
  return function(λ, φ) {
    return [
      /* compute x here */,
      /* compute y here */
    ];
  };
}

Using d3.geo.projectionMutator, you can implement a standard projection that allows the parallels to be changed, reassigning the raw projection used internally by d3.geo.projection:

function albers() {
  var φ0 = 29.5,
      φ1 = 45.5,
      mutate = d3.geo.projectionMutator(albersRaw),
      projection = mutate(φ0, φ1);

  projection.parallels = function(_) {
    if (!arguments.length) return [φ0, φ1];
    return mutate(φ0 = +_[0], φ1 = +_[1]);
  };

  return projection;
}

Thus, when creating a mutable projection, the mutate function is never exposed, but can be used to recreate the underlying raw projection easily. For the full implementation, see src/geo/albers.js.

Standard Projections

# d3.geo.albers()

An alias for d3.geo.conicEqualArea, with USA-centric defaults: scale 1000, translate [480, 250], rotation [96°, 0°], center ⟨-0.6°, 38.7°⟩ and parallels [29.5°, 45.5°], making it suitable for displaying the United States, centered around Hutchinson, Kansas in a 960×500 area. The central meridian and parallels are specified by the USGS in the 1970 National Atlas.

# d3.geo.albersUsa()

The Albers USA projection is a composite projection of four Albers projections designed to display the forty-eight lower United States alongside Alaska and Hawaii. Although intended for choropleths, it scales the area of Alaska by a factor of 0.35x (a lie factor of 3); Hawaii is shown at the same scale as the lower forty-eight.

The Albers USA projection does not support rotation or centering.

# d3.geo.azimuthalEqualArea()

The azimuthal equal-area projection is also suitable for choropleths. A polar aspect of this projection is used for the United Nations logo.

# d3.geo.azimuthalEquidistant()

The azimuthal equidistant projection preserves distances from the projection’s center: the distance from any projected point to the projection’s center is proportional to the great arc distance. Thus, circles around the projection’s center are projected to circles on the Cartesian plane. This can be useful for visualizing distances relative to a point of reference, such as commute distances.

# d3.geo.conicConformal()

Lambert’s conformal conic projection projects the globe conformally onto a cone.

# conicConformal.parallels([parallels])

If parallels is specified, sets the projection’s standard parallels to the specified two-element array of latitudes (in degrees) and returns the projection. If parallels is not specified, returns the current parallels.

# d3.geo.conicEqualArea()

The Albers projection, as an equal-area projection, is recommended for choropleths as it preserves the relative areas of geographic features.

# conicEqualArea.parallels([parallels])

If parallels is specified, sets the Albers projection’s standard parallels to the specified two-element array of latitudes (in degrees) and returns the projection. If parallels is not specified, returns the current parallels. To minimize distortion, the parallels should be chosen to surround the projection’s center.

# d3.geo.conicEquidistant()

# conicEquidistant.parallels([parallels])

If parallels is specified, sets the projection’s standard parallels to the specified two-element array of latitudes (in degrees) and returns the projection. If parallels is not specified, returns the current parallels.

# d3.geo.equirectangular()

The equirectangular, or plate carrée projection, is the simplest possible geographic projection: the identity function. It is neither equal-area nor conformal, but is sometimes used for raster data. See raster reprojection for an example; the source image uses the equirectangular projection.

# d3.geo.gnomonic()

The gnomonic projection is an azimuthal projection that projects great circles as straight lines. See the interactive gnomonic for an example.

# d3.geo.mercator()

The spherical Mercator projection is commonly used by tiled mapping libraries (such as OpenLayers and Leaflet). For an example displaying raster tiles with the Mercator projection, see the d3.geo.tile plugin. It is conformal; however, it introduces severe area distortion at world scale and thus is not recommended for choropleths.

# d3.geo.orthographic()

The orthographic projection is an azimuthal projection suitable for displaying a single hemisphere; the point of perspective is at infinity. See the animated world tour and interactive orthographic for examples. For a general perspective projection, see the satellite projection.

# d3.geo.stereographic()

The stereographic projection is another perspective (azimuthal) projection. The point of perspective is on the surface of the sphere, looking in; it is thus commonly used for celestial charts. See the interactive stereographic for an example.

# d3.geo.transverseMercator()

The transverse Mercator projection.

Raw Projections

D3 exposes several raw projections, designed for reuse when implementing a composite projection (such as Sinu–Mollweide, which combines the raw sinusoidal and Mollweide projections). Raw projections are typically wrapped using d3.geo.projection before use. These are point functions that take spherical coordinates λ and φ (in radians) as input and return a two-element array (also in radians) as output. Many raw projections also implement an inverse projection for mapping from planar to spherical coordinates.

# d3.geo.albers.raw(φ₀, φ₁)

An alias for d3.geo.conicEqualArea.raw.

# d3.geo.azimuthalEqualArea.raw

The raw azimuthal equal-area projection.

# d3.geo.azimuthalEquidistant.raw

The raw azimuthal equidistant projection.

# d3.geo.conicConformal.raw(φ₀, φ₁)

Returns a raw conformal conic projection with the specified parallels in radians.

# d3.geo.conicEqualArea.raw(φ₀, φ₁)

Returns a raw Albers projection with the specified parallels in radians.

# d3.geo.conicEquidistant.raw(φ₀, φ₁)

Returns a raw equidistant conic projection with the specified parallels in radians.