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.

## 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**(φ_{0}, φ_{1})

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**(φ_{0}, φ_{1})

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

# d3.geo.conicEqualArea.**raw**(φ_{0}, φ_{1})

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

# d3.geo.conicEquidistant.**raw**(φ_{0}, φ_{1})

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

# d3.geo.equirectangular.**raw**

The raw equirectangular projection.

# d3.geo.gnomonic.**raw**

The raw gnomonic projection.

# d3.geo.mercator.**raw**

The raw Mercator projection.

# d3.geo.orthographic.**raw**

The raw orthographic projection.

# d3.geo.stereographic.**raw**

The raw stereographic projection.