geokit/mercator

Web Mercator (EPSG:3857) tile and quadkey conversion.

Web Mercator is the projection used by every slippy map service: Google Maps, OpenStreetMap, Bing Maps, Mapbox. The world at zoom level z is divided into 2 ^ z × 2 ^ z square tiles indexed by (x, y) with (0, 0) at the top-left (north-west) corner.

Tiles outside the supported latitude range (±85.05112878°, where the projection clips to keep the map square) are not representable; from_lat_lng clamps latitude rather than reporting an error.

Quadkeys are Bing Maps’ single-string encoding of (zoom, x, y).

Types

MercatorError

</>

Errors returned by tile and quadkey operations.

pub type MercatorError {
  ZoomOutOfRange(zoom: Int)
  TileCoordOutOfRange(zoom: Int, x: Int, y: Int)
  InvalidQuadkeyChar(char: String, position: Int)
  EmptyQuadkey
}

Constructors

```
ZoomOutOfRange(zoom: Int)
```
Zoom level was outside [0, 30].

TileCoordOutOfRange(zoom: Int, x: Int, y: Int)

x or y was outside [0, 2^zoom).

```
InvalidQuadkeyChar(char: String, position: Int)
```
A character outside {0, 1, 2, 3} appeared in a quadkey.
```
EmptyQuadkey
```
quadkey_to_tile was called with an empty string.

Tile

opaque </>

A tile identified by its zoom level and (x, y) coordinates. pub opaque; build through tile and inspect through zoom, x, and y.

pub opaque type Tile

Values

bounds

</>

pub fn bounds(tile tile: Tile) -> #(latlng.LatLng, latlng.LatLng)

The south-west and north-east corners of tile, returned as #(sw, ne).

from_lat_lng

</>

pub fn from_lat_lng(
  point point: latlng.LatLng,
  zoom zoom: Int,
) -> Result(Tile, MercatorError)

Convert a LatLng to the Tile that contains it at the given zoom level.

Latitude is clamped to ±85.05112878° (the Web Mercator pole limit) before projection, so any input LatLng produces a valid tile.

from_quadkey

</>

pub fn from_quadkey(
  quadkey quadkey: String,
) -> Result(Tile, MercatorError)

Decode a quadkey to a Tile. The resulting zoom equals the length of the quadkey, which must be in [1, 30] to mirror the range accepted by new.

new

</>

pub fn new(
  zoom zoom: Int,
  x x: Int,
  y y: Int,
) -> Result(Tile, MercatorError)

Build a Tile. zoom must be in [0, 30]; x and y must each be in [0, 2^zoom).

Matches the constructor naming convention used by every other opaque type in geokit (e.g. latlng.new).

tile

</>

pub fn tile(
  zoom zoom: Int,
  x x: Int,
  y y: Int,
) -> Result(Tile, MercatorError)

Deprecated: Use mercator.new — the constructor was renamed for parity with latlng.new (will be removed in 1.0).

Build a Tile. Alias for new kept for backward compatibility; new code should call new instead.

to_lat_lng

</>

pub fn to_lat_lng(tile tile: Tile) -> latlng.LatLng

Top-left (north-west) corner of tile as a LatLng.

to_quadkey

</>

pub fn to_quadkey(tile tile: Tile) -> String

Encode tile as a Bing-style quadkey. The length of the result equals zoom(tile).

x

</>

pub fn x(tile tile: Tile) -> Int

Tile x coordinate.

y

</>

pub fn y(tile tile: Tile) -> Int

Tile y coordinate.

zoom

</>

pub fn zoom(tile tile: Tile) -> Int

Zoom level of tile.