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, as well as the mollweide projection.
| 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. |
| mollweide | An equal-area, pseudocylindrical map projection generally used for global maps of the world or night sky. ≥ 5.9 |
| 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@2"></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" }
],
...
});