Skip to main content

WebMercatorViewport

From-v3.1

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

Constructor

ParameterTypeDefaultDescription
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)
fovynumbersee belowField of view of camera in degrees
altitudenumbersee belowAltitude of camera in screen units
positionnumber[]nullOffset of the camera, in meters

Remarks:

  • If either altitude or fovy is not provided, the missing value is computed from the other using altitudeToFovy()/fovyToAltitude().
  • Altitude has a default value that matches assumptions in mapbox-gl. It is only used if both altitude and fovy are not supplied.
  • Field of view is independent from altitude, provide altitudeToFovy(1.5) (default value) to match 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.

Methods

project(lngLatZ, options)

Projects latitude and longitude to pixel coordinates on screen.

ParameterTypeDefaultDescription
lngLatZArray(required)map coordinates, [lng, lat] or [lng, lat, Z] where Z is elevation in meters
optionsObject{}named options
options.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].

Remarks:

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

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

ParameterTypeDefaultDescription
xyzArray(required)pixel coordinates, [x, y] or [x, y, z] where z is pixel depth
optionsObject{}named options
options.topLeftBooleantrueIf true projected coords are top left, otherwise bottom left
options.targetZnumber0If pixel depth z is not specified in xyz, use options.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 options.targetZ: returns [lng, lat].
  • If input is [x, y] with options.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.

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

Returns:

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

Unprojects a Web Mercator coordinate to longitude and latitude.

ParameterTypeDefaultDescription
xyArray(required)Web Mercator coordinates, [x, y]
scalenumberthis.scaleWeb Mercator scale

Returns:

  • [longitude, latitude]
getBounds(options)

Get the axis-aligned bounding box of the current visible area.

  • options.z (number, optional) - To calculate a bounding volume for fetching 3D data, this option can be used to get the bounding box at a specific elevation. Default 0.

Returns:

  • [[lon, lat], [lon, lat]] as the south west and north east corners of the smallest orthogonal bounds that encompasses the visible region.
getBoundingRegion(options)

Get the vertices of the current visible region.

  • options.z (number, optional) - To calculate a bounding volume for fetching 3D data, this option can be used to get the bounding region at a specific elevation. Default 0.

Returns:

  • An array of 4 corners in [longitude, latitude, altitude] that define the visible region.
fitBounds(bounds, options: object)

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.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.
  • opts.minExtent (number, optional) - If supplied, the bounds used to calculate the new map settings will be expanded if the delta width or height of the supplied bounds is smaller than this value.
  • opts.maxZoom=24 (number, optional) - The returned zoom value will be capped to this value. Avoids returning infinite zoom when the supplied bounds have zero width or height deltas.

Returns:

  • A new WebMercatorViewport instance
getMapCenterByLngLatPosition(options: object): [number, number]

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

Parameters:

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

Returns:

  • [longitude, latitude] as the new map center