Table of Contents


The WebMercatorViewport class takes map camera states (latitude, longitude, zoom, pitch, bearing etc.), and performs projections between world and screen coordinates.


widthNumber1Width of viewport
heightNumber1Height of viewport
latitudeNumber0Latitude of viewport center
longitudeNumber0Longitude of viewport center
zoomNumber11Map zoom (scale is calculated as 2^zoom)
pitchNumber0The pitch (tilt) of the map from the screen, in degrees (0 is straight down)
bearingNumber0The bearing (rotation) of the map from north, in degrees counter-clockwise (0 means north is up)
altitudeNumber1.5Altitude of camera in screen units


  • Altitude has a default value that matches assumptions in mapbox-gl
  • width and height are forced to 1 if supplied as 0, to avoid division by zero. This is intended to reduce the burden of apps to to check values before instantiating a Viewport.
  • When using Mercator projection, per cartographic tradition, longitudes and latitudes are specified as degrees.


project(lngLatZ, opts)

Projects latitude and longitude to pixel coordinates on screen.

lngLatZArray(required)map coordinates, [lng, lat] or [lng, lat, Z] where Z is elevation in meters
optsObject{}named options
opts.topLeftBooleantrueIf true projected coords are top left, otherwise bottom left

Returns: [x, y] or [x, y, z] in pixels coordinates. z is pixel depth.

  • If input is [lng, lat]: returns [x, y].
  • If input is [lng, lat, Z]: returns [x, y, z].


  • By default, returns top-left coordinates suitable for canvas/SVG type rendering.
unproject(xyz, opts)

Unproject pixel coordinates on screen to longitude and latitude on map.

xyzArray(required)pixel coordinates, [x, y] or [x, y, z] where z is pixel depth
optsObject{}named options
opts.topLeftBooleantrueIf true projected coords are top left, otherwise bottom left
opts.targetZNumber0If pixel depth z is not specified in xyz, use opts.targetZ as the desired elevation

Returns: [lng, lat] or [longitude, lat, Z] in map coordinates. Z is elevation in meters.

  • If input is [x, y] without specifying opts.targetZ: returns [lng, lat].
  • If input is [x, y] with opts.targetZ: returns [lng, lat, targetZ].
  • If input is [x, y, z]: returns [lng, lat, Z].
projectFlat(lngLat, scale)

Project longitude and latitude onto Web Mercator coordinates.

lngLatArray(required)map coordinates, [lng, lat]
scaleNumberthis.scaleWeb Mercator scale


  • [x, y], representing Web Mercator coordinates.
unprojectFlat(xy, scale)

Unprojects a Web Mercator coordinate to longitude and latitude. | Parameter | Type | Default | Description | | -------------- | --------- | -------- | ------------------------------- | | xy | Array | (required) | Web Mercator coordinates, [x, y] | | scale | Number | this.scale | Web Mercator scale |


  • [longitude, latitude]
fitBounds(bounds, options)

Get a new flat viewport that fits around the given bounding box.

  • bounds ([[Number,Number],[Number,Number]]) - an array of two opposite corners of the bounding box. Each corner is specified in [lon, lat].
  • options (Object)

    • options.padding (Number|{top:Number, bottom: Number, left: Number, right: Number}, optional) - The amount of padding in pixels to add to the given bounds from the edge of the viewport. If padding is set as object, all parameters are required.
    • options.offset ([Number,Number], optional) - The center of the given bounds relative to the viewport's center, [x, y] measured in pixels.

Returns the map center that place a given [lng, lat] coordinate at screen point [x, y].


  • opts (Object) - options
  • opts.lngLat (Array, required) - [lng,lat] coordinates of a location on the sphere.
  • opts.pos (Array, required) - [x,y] coordinates of a pixel on screen.


  • [longitude, latitude] new map center