Projection
Edit this pageA cartographic projection maps longitude and latitude pairs to x, y coordinates. As with Vega, one can use projections in Vega-Lite to layout both geographic points (such as locations on a map) represented by longitude and latitude coordinates, or to project geographic regions (such as countries and states) represented using the GeoJSON format. Projections are specified at the unit specification level, alongside encoding. Geographic coordinate data can then be mapped to longitude
and latitude
channels (and longitude2
and latitude2
for ranged marks).
For example, this example chart shows all airports in the United States by projecting latitude
, longitude
as x
, y
coordinates using the albersUsa projection.
See the example gallery for more examples with geographic projection.
Documentation Overview
Projection Properties
Property | Type | Description |
---|---|---|
type | String | ExprRef |
The cartographic projection to use. This value is case-insensitive, for example Default value: |
center | Array | ExprRef |
The projection’s center, a two-element array of longitude and latitude in degrees. Default value: |
clipAngle | Number | ExprRef |
The projection’s clipping circle radius to the specified angle in degrees. If |
clipExtent | Array | ExprRef |
The projection’s viewport clip extent to the specified bounds in pixels. The extent bounds are specified as an array |
fit | Fit | Fit[] | ExprRef | |
parallels | Number[] | ExprRef |
For conic projections, the two standard parallels that define the map layout. The default depends on the specific conic projection used. |
pointRadius | Number | ExprRef |
The default radius (in pixels) to use when drawing GeoJSON Default value: |
precision | Number | ExprRef |
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 |
rotate | Array | Array | ExprRef |
The projection’s three-axis rotation to the specified angles, which must be a two- or three-element array of numbers [ Default value: |
scale | Number | ExprRef |
The projection’s scale (zoom) factor, overriding automatic fitting. 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 | Array | ExprRef |
The projection’s translation offset as a two-element array |
If you want to explore the various available properties in more depth, Vega’s projection documentation hosts a useful demo
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
.
Note: All properties of projections are optional with defaults as defined in the Vega projection properties. Because of this, marks that don’t have explicitly defined projections may implicitly derive a projection. Implicit projections will be added for any geoshape
mark, any encoding with field of geojson
type, and encoding with latitude
or longitude
channels.
Projection Types
Vega-Lite 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 use longitude, latitude directly. |
gnomonic | The gnomonic projection. |
identity | The identity projection. Also supports additional boolean reflectX and reflectY parameters. |
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. |
Projection Configuration
// Top-level View Specification
{
...,
"config": { // Configuration Object
"projection": { ... }, // - Projection Configuration
...
}
}
The projection
property of the config
object determines the default properties and transformations applied to different types of projections. The projection config can contain any of the projection properties as specified above.