Comprehensive collection of cartographic projections for transforming spherical coordinates to planar coordinates. d3-geo includes azimuthal, conic, cylindrical, and specialized projections, each optimized for different cartographic applications and geographic regions.
Creates a new projection from a raw projection function.
/**
* Creates a new projection from a raw projection function
* @param project - Raw projection function that transforms [lambda, phi] to [x, y]
* @returns Configurable projection instance
*/
function geoProjection(project: ProjectionFunction): Projection;
/**
* Creates a projection factory function for projections with parameters
* @param projectAt - Function that creates a raw projection function
* @returns Factory function that creates projection instances
*/
function geoProjectionMutator(projectAt: (...args: any[]) => ProjectionFunction): (...args: any[]) => Projection;
type ProjectionFunction = (lambda: number, phi: number) => [number, number];The most common web mapping projection, conforming but not equal-area.
/**
* Creates a Mercator projection
* @returns Mercator projection instance
*/
function geoMercator(): MercatorProjection;
/**
* Raw Mercator projection function
* @param lambda - Longitude in radians
* @param phi - Latitude in radians
* @returns Projected coordinates [x, y]
*/
function geoMercatorRaw(lambda: number, phi: number): [number, number];
interface MercatorProjection extends Projection {
// Inherits all standard projection methods
}Usage Examples:
import { geoMercator } from "d3-geo";
// Create basic Mercator projection
const projection = geoMercator();
// Configure for web map tile display
const webMercator = geoMercator()
.scale(256 / (2 * Math.PI))
.translate([128, 128]);
// Fit to specific geographic bounds
const bounds = [[-10, 50], [10, 60]]; // Europe subset
const mercator = geoMercator().fitExtent([[0, 0], [960, 500]], {
type: "Polygon",
coordinates: [[bounds[0], [bounds[1][0], bounds[0][1]], bounds[1], [bounds[0][0], bounds[1][1]], bounds[0]]]
});Mercator projection rotated 90 degrees, useful for narrow north-south regions.
/**
* Creates a Transverse Mercator projection
* @returns Transverse Mercator projection instance
*/
function geoTransverseMercator(): Projection;
/**
* Raw Transverse Mercator projection function
* @param lambda - Longitude in radians
* @param phi - Latitude in radians
* @returns Projected coordinates [x, y]
*/
function geoTransverseMercatorRaw(lambda: number, phi: number): [number, number];Simple cylindrical projection where meridians and parallels are straight lines.
/**
* Creates an Equirectangular projection
* @returns Equirectangular projection instance
*/
function geoEquirectangular(): Projection;
/**
* Raw Equirectangular projection function
* @param lambda - Longitude in radians
* @param phi - Latitude in radians
* @returns Projected coordinates [x, y]
*/
function geoEquirectangularRaw(lambda: number, phi: number): [number, number];Equal-area conic projection ideal for mid-latitude regions.
/**
* Creates an Albers equal-area conic projection
* @returns Albers projection instance with standard parallels at 29.5° and 45.5°
*/
function geoAlbers(): AlbersProjection;
/**
* Creates a conic equal-area projection
* @returns Conic equal-area projection instance
*/
function geoConicEqualArea(): ConicProjection;
/**
* Raw conic equal-area projection function
* @param phi0 - First standard parallel in radians
* @param phi1 - Second standard parallel in radians
* @returns Raw projection function
*/
function geoConicEqualAreaRaw(phi0: number, phi1: number): ProjectionFunction;
interface AlbersProjection extends ConicProjection {
// Inherits all conic projection methods
}
interface ConicProjection extends Projection {
parallels(parallels?: [number, number]): this | [number, number];
}Usage Examples:
import { geoAlbers, geoConicEqualArea } from "d3-geo";
// US-focused Albers projection
const usAlbers = geoAlbers()
.scale(1000)
.translate([480, 250]);
// Custom conic equal-area for Europe
const europeProjection = geoConicEqualArea()
.parallels([40, 60])
.center([10, 50])
.scale(1000);Conformal conic projection preserving angles.
/**
* Creates a Lambert conformal conic projection
* @returns Lambert conformal conic projection instance
*/
function geoConicConformal(): ConicProjection;
/**
* Raw conformal conic projection function
* @param phi0 - First standard parallel in radians
* @param phi1 - Second standard parallel in radians
* @returns Raw projection function
*/
function geoConicConformalRaw(phi0: number, phi1: number): ProjectionFunction;Conic projection with accurate distances along meridians.
/**
* Creates an equidistant conic projection
* @returns Equidistant conic projection instance
*/
function geoConicEquidistant(): ConicProjection;
/**
* Raw equidistant conic projection function
* @param phi0 - First standard parallel in radians
* @param phi1 - Second standard parallel in radians
* @returns Raw projection function
*/
function geoConicEquidistantRaw(phi0: number, phi1: number): ProjectionFunction;Perspective projection as if viewed from infinite distance.
/**
* Creates an orthographic projection
* @returns Orthographic projection instance
*/
function geoOrthographic(): Projection;
/**
* Raw orthographic projection function
* @param lambda - Longitude in radians
* @param phi - Latitude in radians
* @returns Projected coordinates [x, y]
*/
function geoOrthographicRaw(lambda: number, phi: number): [number, number];Conformal azimuthal projection.
/**
* Creates a stereographic projection
* @returns Stereographic projection instance
*/
function geoStereographic(): Projection;
/**
* Raw stereographic projection function
* @param lambda - Longitude in radians
* @param phi - Latitude in radians
* @returns Projected coordinates [x, y]
*/
function geoStereographicRaw(lambda: number, phi: number): [number, number];Equal-area azimuthal projection (Lambert azimuthal equal-area).
/**
* Creates an azimuthal equal-area projection
* @returns Azimuthal equal-area projection instance
*/
function geoAzimuthalEqualArea(): Projection;
/**
* Raw azimuthal equal-area projection function
* @param lambda - Longitude in radians
* @param phi - Latitude in radians
* @returns Projected coordinates [x, y]
*/
function geoAzimuthalEqualAreaRaw(lambda: number, phi: number): [number, number];Azimuthal projection with accurate distances from center.
/**
* Creates an azimuthal equidistant projection
* @returns Azimuthal equidistant projection instance
*/
function geoAzimuthalEquidistant(): Projection;
/**
* Raw azimuthal equidistant projection function
* @param lambda - Longitude in radians
* @param phi - Latitude in radians
* @returns Projected coordinates [x, y]
*/
function geoAzimuthalEquidistantRaw(lambda: number, phi: number): [number, number];Great circles appear as straight lines.
/**
* Creates a gnomonic projection
* @returns Gnomonic projection instance
*/
function geoGnomonic(): Projection;
/**
* Raw gnomonic projection function
* @param lambda - Longitude in radians
* @param phi - Latitude in radians
* @returns Projected coordinates [x, y]
*/
function geoGnomonicRaw(lambda: number, phi: number): [number, number];Composite projection combining Albers for the continental US with insets for Alaska and Hawaii.
/**
* Creates an Albers USA composite projection
* @returns Albers USA projection instance
*/
function geoAlbersUsa(): Projection;Usage Examples:
import { geoAlbersUsa } from "d3-geo";
// Create US-optimized projection
const projection = geoAlbersUsa()
.scale(1000)
.translate([480, 250]);
// Ideal for choropleth maps of US states
const path = geoPath(projection);
const statePaths = usStates.features.map(state => ({
...state,
path: path(state)
}));Pseudocylindrical equal-area projection designed for world maps.
/**
* Creates an Equal Earth projection
* @returns Equal Earth projection instance
*/
function geoEqualEarth(): Projection;
/**
* Raw Equal Earth projection function
* @param lambda - Longitude in radians
* @param phi - Latitude in radians
* @returns Projected coordinates [x, y]
*/
function geoEqualEarthRaw(lambda: number, phi: number): [number, number];Pseudocylindrical projection optimized for world maps.
/**
* Creates a Natural Earth projection
* @returns Natural Earth projection instance
*/
function geoNaturalEarth1(): Projection;
/**
* Raw Natural Earth projection function
* @param lambda - Longitude in radians
* @param phi - Latitude in radians
* @returns Projected coordinates [x, y]
*/
function geoNaturalEarth1Raw(lambda: number, phi: number): [number, number];Pass-through projection for pre-projected coordinates.
/**
* Creates an identity projection for pre-projected geometry
* @returns Identity projection instance
*/
function geoIdentity(): IdentityProjection;
interface IdentityProjection extends Projection {
reflectX(reflect?: boolean): this | boolean;
reflectY(reflect?: boolean): this | boolean;
scaleX(scale?: number): this | number;
scaleY(scale?: number): this | number;
translateX(translate?: number): this | number;
translateY(translate?: number): this | number;
}All projections implement the standard projection interface:
interface Projection {
/**
* Projects the specified point [longitude, latitude] in degrees
* @param point - Point to project as [longitude, latitude]
* @returns Projected point as [x, y] or null if not projectable
*/
(point: [number, number]): [number, number] | null;
/**
* Inverse projection from planar to spherical coordinates
* @param point - Projected point as [x, y]
* @returns Unprojected point as [longitude, latitude] or null if not invertible
*/
invert?(point: [number, number]): [number, number] | null;
/**
* Sets or gets the projection's scale factor
* @param scale - Scale factor (default 150)
* @returns This projection or current scale
*/
scale(scale?: number): this | number;
/**
* Sets or gets the projection's translation offset
* @param translate - Translation as [x, y] (default [480, 250])
* @returns This projection or current translation
*/
translate(translate?: [number, number]): this | [number, number];
/**
* Sets or gets the projection's center point
* @param center - Center as [longitude, latitude] (default [0, 0])
* @returns This projection or current center
*/
center(center?: [number, number]): this | [number, number];
/**
* Sets or gets the projection's rotation angles
* @param rotate - Rotation as [λ, φ, γ] in degrees (default [0, 0, 0])
* @returns This projection or current rotation
*/
rotate(rotate?: [number, number, number?]): this | [number, number, number];
/**
* Sets or gets the projection's clipping circle radius
* @param angle - Clipping angle in degrees (null for antimeridian clipping)
* @returns This projection or current clip angle
*/
clipAngle(angle?: number | null): this | number | null;
/**
* Sets or gets the projection's clipping extent
* @param extent - Clipping extent as [[x0, y0], [x1, y1]] (null for no clipping)
* @returns This projection or current clip extent
*/
clipExtent(extent?: [[number, number], [number, number]] | null): this | [[number, number], [number, number]] | null;
/**
* Sets or gets the projection's precision for adaptive sampling
* @param precision - Precision in pixels (default 0.5)
* @returns This projection or current precision
*/
precision(precision?: number): this | number;
/**
* Scales and translates to fit the specified object within the extent
* @param extent - Target extent as [[x0, y0], [x1, y1]]
* @param object - GeoJSON object to fit
* @returns This projection
*/
fitExtent(extent: [[number, number], [number, number]], object: GeoJSON.Feature | GeoJSON.Geometry): this;
/**
* Scales and translates to fit the specified object within the size
* @param size - Target size as [width, height]
* @param object - GeoJSON object to fit
* @returns This projection
*/
fitSize(size: [number, number], object: GeoJSON.Feature | GeoJSON.Geometry): this;
/**
* Scales and translates to fit the specified object within the width
* @param width - Target width
* @param object - GeoJSON object to fit
* @returns This projection
*/
fitWidth(width: number, object: GeoJSON.Feature | GeoJSON.Geometry): this;
/**
* Scales and translates to fit the specified object within the height
* @param height - Target height
* @param object - GeoJSON object to fit
* @returns This projection
*/
fitHeight(height: number, object: GeoJSON.Feature | GeoJSON.Geometry): this;
/**
* Returns a projection stream for the specified output stream
* @param stream - Output stream
* @returns Transform stream
*/
stream(stream: Transform): Transform;
}Common Usage Examples:
import { geoMercator, geoAlbers, geoOrthographic } from "d3-geo";
// Configure Mercator for web maps
const webMercator = geoMercator()
.scale(256 / (2 * Math.PI))
.translate([128, 128]);
// Configure Albers for US data
const usProjection = geoAlbers()
.scale(1000)
.translate([480, 250])
.rotate([96, 0])
.center([-0.6, 38.7]);
// Interactive globe with orthographic
const globe = geoOrthographic()
.scale(250)
.translate([480, 250])
.clipAngle(90);
// Rotate globe interactively
function rotateGlobe(longitude, latitude) {
globe.rotate([-longitude, -latitude]);
}
// Fit projection to data bounds
const projection = geoMercator();
const geojsonData = { /* your GeoJSON data */ };
projection.fitSize([960, 500], geojsonData);