Geo Projections
Wiki ▸ API Reference ▸ Geo ▸ Geo Projections
These 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
|
These 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
|
Most projections provided by D3 are instances of d3.geo.projection. These projections provide a number of convenient methods for configuring the projection, such as rotating the globe, and scaling or transforming the canvas.
# d3.geo.projection(raw)
…
# projection(location)
…
# projection.invert(point)
…
# projection.rotate(rotation)
…
# projection.center(center)
…
# projection.translate(translation)
…
# projection.scale(scale)
…
# projection.clipAngle(angle)
…
# projection.precision(precision)
…
# projection.stream(listener)
…
# d3.geo.projectionMutator(rawCreate)
…
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. This are point functions that take spherical coordinates in radians as input and return a two-element array of normalized coordinates (typically in 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(λ, φ)
…
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.
# d3.geo.mercator()
Construct a new spherical Mercator projection with the default scale (500) and translate ([480, 250]). The default Mercator projection is appropriate for displaying the entire world in a 960×500 area.
# mercator(location)
The forward projection: returns a two-element array [x, y] given the input [longitude, latitude].
# mercator.invert(point)
The inverse projection: returns a two-element array [longitude, latitude] given the input [x, y].
# mercator.scale([scale])
Get or set the projection’s scale factor. 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 500. The scale factor corresponds linearly to the distance between projected points. Note that scale factors may not be consistent across projection types (e.g., Mercator and Albers).
# mercator.translate([offset])
Get or set the projection's translation offset. If offset is specified, sets the projection’s translation offset to the specified two-element array [x, y] and returns the projection. If offset 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.
The Albers equal-area projection is highly recommended for choropleths as it preserves the relative areas of geographic features. However, you must determine appropriate parallels and origin.
# d3.geo.albers()
Construct a new Albers equal-area conic projection with the default scale (1000), translate ([480, 250]), origin ([-98, 38]) and parallels ([29.5, 45.5]). The default Albers projection is appropriate for displaying the United States in a 960×500 area. The parallels of 29.5º and 45.5º were chosen by the USGS in their 1970 National Atlas.
# albers(location)
The forward projection: returns a two-element array [x, y] given the input [longitude, latitude].
# albers.invert(point)
The inverse projection: returns a two-element array [longitude, latitude] given the input [x, y].
# albers.origin([origin])
Get or set the projection’s origin. If origin is specified, sets the projection’s origin to the specified two-element array [longitude, latitude] and returns the projection. If origin is not specified, returns the current origin, which defaults to [-98, 38] (Hutchinson, Kansas). To minimize the distortion of parallel lines, the origin should be chosen to be near the center of the region of interest.
# albers.parallels([parallels])
Get or set the projection’s two standard parallels. If parallels is specified, sets the projection’s parallels to the specified two-element array of latitudes and returns the projection. If parallels is not specified, returns the current parallels, which default to [29.5, 45.5]. To minimize the distortion of parallel lines, the parallels should surround the origin and cover the region of interest.
# albers.scale([scale])
Get or set the projection’s scale factor. 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 1000. The scale factor corresponds linearly to the distance between projected points. Note that scale factors may not be consistent across projection types (e.g., Mercator and Albers).
# albers.translate([offset])
Get or set the projection's translation offset. If offset is specified, sets the projection’s translation offset to the specified two-element array [x, y] and returns the projection. If offset is not specified, returns the current translation offset which defaults to [480, 250]. The translation offset determines the pixel coordinates of the origin. The default value is designed to place Hutchinson, Kansas at the center of a 960×500 area.
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 (1.5x) and Alaska (0.6x); Hawaii is shown at the same scale as the lower forty-eight.
The projection composition is implemented as:
function albersUsa(coordinates) {
var lon = coordinates[0],
lat = coordinates[1];
return (lat > 50 ? alaska
: lon < -140 ? hawaii
: lat < 21 ? puertoRico
: lower48)(coordinates);
}The Albers USA projection does not currently support inversion.
# d3.geo.albersUsa()
Construct a new composite Albers projection for the United States.
# albersUsa(location)
The forward projection: returns a two-element array [x, y] given the input [longitude, latitude].
# albersUsa.scale([scale])
Get or set the projection’s scale factor. 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 1000. The scale factor corresponds linearly to the distance between projected points. Note that scale factors may not be consistent across projection types (e.g., Mercator and Albers).
(As noted above, a scale factor of 1000 corresponds to a scale of 1500 for Puerto Rico and 600 for Alaska.)
# albersUsa.translate([offset])
Get or set the projection's translation offset. If offset is specified, sets the projection’s translation offset to the specified two-element array [x, y] and returns the projection. If offset is not specified, returns the current translation offset which defaults to [480, 250]. The translation offset determines the pixel coordinates of the origin. The default value is designed to place Hutchinson, Kansas at the center of a 960×500 area.
D3’s azimuthal projection implementation encompasses [orthographic](http://en.wikipedia.org/wiki/Orthographic_projection_(cartography\)), stereographic, gnomonic, equidistant and equal-area projections.
# d3.geo.azimuthal()
Construct a new Azimuthal projection with the default mode (orthographic), origin (⟨0, 0⟩), scale (200) and translate ([480, 250]). The default projection shows the hemisphere centered around null island in a 960×500 area. Azimuthal projections should typically be used in conjunction with d3.geo.circle’s clip method to avoid showing the back-facing hemisphere.
# azimuthal(location)
The forward projection: returns a two-element array [x, y] given the input [longitude, latitude].
# azimuthal.mode([mode])
Get or set the projection’s mode. If mode is specified, sets the projection mode to the specified string and returns the projection. If mode is not specified, returns the current mode which defaults to orthographic. The allowed modes are:
- orthographic
- stereographic
- gnomonic
- equidistant
- equalarea
See this interactive example for a demonstration of the different projection modes.
# azimuthal.origin([origin])
Get or set the projection’s origin. If origin is specified, sets the projection’s origin to the specified two-element array [longitude, latitude] and returns the projection. If origin is not specified, returns the current origin, which defaults to [0, 0] (null island). To minimize distortion, the origin should be chosen to be near the center of the region of interest.
# azimuthal.scale([scale])
Get or set the projection’s scale factor. 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 200. The scale factor corresponds linearly to the distance between projected points. Note that scale factors may not be consistent across projection types (e.g., Mercator and Albers).
# azimuthal.translate([offset])
Get or set the projection's translation offset. If offset is specified, sets the projection’s translation offset to the specified two-element array [x, y] and returns the projection. If offset is not specified, returns the current translation offset which defaults to [480, 250]. The translation offset determines the pixel coordinates of the origin. The default value is designed to place Null Island at the center of a 960×500 area.