# 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 | A unique name for the projection. Projections and scales share the same namespace; names must be unique across both.Required. |

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

pointRadius | Number | Sets 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 | 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. 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`

.

## 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 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" }
],
...
});
```