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 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].
precision String 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.
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.
equirectangular The equirectangular (plate carrée) projection, akin to use longitude, latitude directly.
gnomonic The gnomonic projection.
mercator The spherical Mercator projection. Uses a default clipExtent such that the world is projected to a square, clipped to approximately ±85° latitude.
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. For example:

// d3-geo-projections must be imported and added to d3 object
// to register with Vega, provide a name and d3 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" }
  ],
  ...
});