Projection

Edit this page

A 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. Projection’s 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.

Projection Properties

Property	Type	Description
type	String	The cartographic projection to use. This value is case-insensitive, for example `"albers"` and `"Albers"` indicate the same projection type. You can find all valid projection types in the documentation. Default value: `mercator`
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	Number[]	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.
center	Number[]	Sets the projection’s center to the specified center, a two-element array of longitude and latitude in degrees. Default value: `[0, 0]`
scale	Number	Sets the projection’s scale (zoom) value, overriding automatic fitting.
translate	Number[]	Sets the projection’s translation (pan) value, overriding automatic fitting.
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.) Default value: `[0, 0, 0]`
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…`.

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.
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.