Geo Projections

Wiki ▸ API Reference ▸ Geo ▸ Geo Projections

Standard Projections

Several common projections are included with default build of D3.

d3.geo.albers	d3.geo.albersUsa	d3.geo.azimuthalEqualArea	d3.geo.azimuthalEquidistant
d3.geo.equirectangular	d3.geo.gnomonic	d3.geo.mercator	d3.geo.orthographic
d3.geo.stereographic

Extended Projections

Numerous less-common projections are available in the extended geographic projections plugin.

d3.geo.aitoff	d3.geo.august	d3.geo.bonne	d3.geo.collignon
d3.geo.conicConformal	d3.geo.conicEquidistant	d3.geo.cylindricalEqualArea	d3.geo.eckert1
d3.geo.eckert2	d3.geo.eckert3	d3.geo.eckert4	d3.geo.eckert5
d3.geo.eckert6	d3.geo.eisenlohr	d3.geo.gringorten	d3.geo.guyou
d3.geo.hammer	d3.geo.homolosine	d3.geo.kavrayskiy7	d3.geo.lagrange
d3.geo.larrivee	d3.geo.miller	d3.geo.mollweide	d3.geo.nellHammer
d3.geo.peirceQuincuncial	d3.geo.polyconic	d3.geo.robinson	d3.geo.satellite
d3.geo.sinusoidal	d3.geo.sinuMollweide	d3.geo.vanDerGrinten	d3.geo.wagner6
d3.geo.winkel3

Standard Abstract Projection

Most projections provided by D3 are instances of d3.geo.projection, and are configurable: you can rotate the globe, scale or transform the canvas, etc. Unless you’re defining a new projection, you won’t use d3.geo.projection directly; you’ll use one of the provided implementations.

# 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 [
    λ / (2 * π),
    Math.max(-.5, Math.min(+.5, Math.log(Math.tan(π / 4 + φ / 2)) / (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 a two-element array [x, y] given the input [longitude, latitude].

# projection.invert(point)

Projects backward from Cartesian coordinates (in pixels) to spherical coordinates (in degrees). Returns a two-element array [longitude, latitude] given the input [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. 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 center is specified, sets the projection’s center to the specified location, a two-element array of longitude and latitude in degrees. 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 origin ([0, 0] in longitude and latitude). The default value is designed to place null island 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. 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.

# projection.precision(precision)

If precision is specified, sets the threshold for the projection’s adaptive resampling to the specified value in pixels. This value corresponds to the Douglas–Peucker distance. If precision is not specified, returns the projection’s current resampling precision which defaults to Math.SQRT1_2.

# 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 projections 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()

The Albers projection, as an equal-area projection, is recommended for choropleths as it preserves the relative areas of geographic features. The default Albers equal-area conic projection has scale 1000, translate [480, 250], rotation [98, 0], center [0, 38] and parallels [29.5, 45.5], making it suitable for displaying the United States, centered around Hutchinson, Kansas in a 960×500 area. The parallels of 29.5° and 45.5° were chosen by the USGS in their 1970 National Atlas.

# albers.parallels([parallels])

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

# 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, Hawaii and Puerto Rico. Although intended for choropleths, it distorts the area of Puerto Rico by a factor of 1.5x and Alaska by a factor of 0.6x; Hawaii is shown at the same scale as the lower forty-eight.

The projection composition is implemented as:

function albersUsa(location) {
  var longitude = location[0],
      latitude = location[1];
  return (latitude > 50 ? alaska
      : longitude < -140 ? hawaii
      : latitude < 21 ? puertoRico
      : lower48)(coordinates);
}

The Albers USA projection does not support inversion, rotation, or centering.

# d3.geo.azimuthalEqualArea()

The azimuthal equal-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.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.

# d3.geo.mercator()

The spherical Mercator projection is commonly used by tiled mapping libraries (such as OpenLayers and Leaflet). For displaying raster tiles, 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. The default scale is 500, appropriate for displaying the entire world in a 960×500 area.

# 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 for an example. 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.

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. These are point functions that take spherical coordinates (in radians) as input and return a two-element array (in normalized coordinates, typically between -1 and 1) as output. Many raw projections also implement an inverse projection for mapping from normalized to spherical coordinates.

# d3.geo.albers.raw(λ, φ)

…

# d3.geo.azimuthalEqualArea.raw(λ, φ)

…

# d3.geo.azimuthalEquidistant.raw(λ, φ)

…

# d3.geo.equirectangular.raw(λ, φ)

…

# d3.geo.gnomonic.raw(λ, φ)

…

# d3.geo.mercator.raw(λ, φ)

…

# d3.geo.orthographic.raw(λ, φ)

…

# d3.geo.stereographic.raw(λ, φ)

…