Geo Projections - InfographicsJa/d3 GitHub Wiki
Wiki ▸ API Reference ▸ Geo ▸ Geo Projections
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.
# 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.
Albers
The Albers equal-area projection is highly recommended for choropleths as it does not 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.
Albers USA (Composite)
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.)
# 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.
Azimuthal
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.