Projections

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 The projection’s clipping circle radius, specified as an angle in degrees. If null, switches to antimeridian cutting rather than small-circle clipping.
clipExtent Array The projection’s viewport clip extent, as a set of pixel bounds. 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 The projection’s scale factor. 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[ ] The projection’s translation offset as a 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[ ] The projection’s center, a two-element array of longitude and latitude in degrees. The default value is [0, 0].
rotate Number[ ] The projection’s three-axis rotation angles. The value 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].
parallels Number[ ] For conic projections, the two standard parallels that define the map layout. The default depends on the specific conic projection used.
pointRadius Number 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 The threshold for the projection’s adaptive resampling 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.

Alternative default values for any of the properties above can be set using a custom config object.

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.
azimuthalEquidistant 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="https://cdn.jsdelivr.net/npm/vega-projection-extended@1.0.0"></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" }
  ],
  ...
});