Cartographic projections map (longitude, latitude) pairs to projected (x, y) coordinates. Vega uses projections to layout both geographic points (such as locations on a map) for which longitude and latitude coordinates are part of the input data, and geographic regions (such as countries and states) represented using the GeoJSON format.

Documentation Overview

Projection Properties

Property Type Description
name String Required. A unique name for the projection. Projections and scales share the same namespace; names must be unique across both.
type String The cartographic projection to use. The default is "mercator". This value is case-insensitive, for example "albers" and "Albers" indicate the same projection type.
clipAngle Number Sets the projection’s clipping circle radius to the specified angle in degrees. If null, switches to antimeridian cutting rather than small-circle clipping.
clipExtent Array Sets the projection’s viewport clip extent to the specified bounds in pixels. 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 null, no viewport clipping is performed.
scale Number Sets the projection’s scale factor to the specified value. The default scale is projection-specific. The scale factor corresponds linearly to the distance between projected points; however, scale factor values are not equivalent across projections.
translate Number[ ] Sets the projection’s translation offset to the specified two-element array [tx, ty]. If translate 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.
center Number[ ] Sets the projection’s center to the specified center, a two-element array of longitude and latitude in degrees. The default value is [0, 0].
rotate Number[ ] Sets the projection’s three-axis rotation to the specified angles, which must be a two- or three-element array of numbers [lambda, phi, gamma] specifying the rotation angles in degrees about each spherical axis. (These correspond to yaw, pitch and roll.) The default value is [0, 0, 0].
pointRadius Number Sets the default radius (in pixels) to use when drawing GeoJSON Point and MultiPoint geometries. This parameter sets a constant default value, to modify the point radius in response to data, see the corresponding parameter of the GeoPath and GeoShape transforms. The default value is 4.5.
precision Number 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 √0.5 ≅ 0.70710…
fit Object | Array GeoJSON data to which the projection should attempt to automatically fit the translate and scale parameters. If object-valued, this parameter should be a GeoJSON Feature or FeatureCollection. If array-valued, each array member may be a GeoJSON Feature, FeatureCollection, or a sub-array of GeoJSON Features.
extent Array[ ] Used in conjunction with fit, provides the pixel area to which the projection should be automatically fit. The extent bounds are specified as an array [[x0, y0], [x1, y1]], where x0 is the left side of the extent, y0 is the top, x1 is the right and y1 is the bottom.
size Number[ ] Used in conjunction with fit, provides the width and height in pixels of the area to which the projection should be automatically fit. This parameter is equivalent to an extent of [[0,0], size].

In addition to the shared properties above, the following properties are supported for specific projection types in the d3-geo-projection library: coefficient, distance, fraction, lobes, parallel, radius, ratio, spacing, tilt.

Projection Types

Vega includes all cartographic projections provided by the d3-geo library.

Type Description
albers The Albers’ equal-area conic projection. This is a U.S.-centric configuration of "conicEqualArea".
albersUsa A U.S.-centric composite with projections for the lower 48 states, Hawaii, and Alaska (scaled to 0.35 times the true relative area).
azimuthalEqualArea The azimuthal equal-area projection.
azimuthalEquidistanct The azimuthal equidistant projection.
conicConformal The conic conformal projection. The parallels default to [30°, 30°] resulting in flat top.
conicEqualArea The Albers’ equal-area conic projection.
conicEquidistant The conic equidistant projection.
equalEarth The Equal Earth projection, by Bojan Šavrič et al., 2018.
equirectangular The equirectangular (plate carrée) projection, akin to using longitude, latitude directly.
gnomonic The gnomonic projection.
identity The identity transform, which can be used to translate, scale, and clip planar geometry. Also supports additional boolean reflectX and reflectY parameters. ≥ 3.3
mercator The spherical Mercator projection. Uses a default clipExtent such that the world is projected to a square, clipped to approximately ±85° latitude.
naturalEarth1 The Natural Earth projection is a pseudocylindrical projection designed by Tom Patterson. It is neither conformal nor equal-area, but appealing to the eye for small-scale maps of the whole world. ≥ 4.0
orthographic The orthographic projection.
stereographic The stereographic projection.
transverseMercator The transverse spherical Mercator projection. Uses a default clipExtent such that the world is projected to a square, clipped to approximately ±85° latitude.

Register Additional Projections

Vega can be extended with additional projections, such as those found in the d3-geo-projection library.

To register all extended projections from d3-geo-projection with Vega, simply import the vega-projection-extended library:

<script src=""></script>

Alternatively, custom projections can be manually registered using the vega.projection method:

// Assumes d3-geo-projection is imported under the d3 variable.
// To register with Vega, provide a name and projection function.
vega.projection('winkel3', d3.geoWinkel3);

// Vega parser and runtime now support the 'winkel3' projection
var runtime = vega.parse({
  "projections": [
    { "name": "proj", "type": "winkel3" }