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.gnomonic	d3.geo.mercator	d3.geo.orthographic	d3.geo.stereographic
d3.geo.equirectangular

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 default rotation [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 default center [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 default clip angle, which is 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)

…

# d3.geo.projectionMutator(rawCreate)

…

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])

… To minimize the distortion of parallel lines, the origin should be chosen to be near the center of the region of interest.

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

…

# d3.geo.azimuthalEquidistant()

…

# d3.geo.equirectangular()

…

# d3.geo.gnomonic()

…

# d3.geo.mercator()

The spherical Mercator projection is commonly used by tiled mapping libraries (such as OpenLayers and Leaflet). 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()

…

# d3.geo.stereographic()

…

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(λ, φ)

…