WebMercatorViewport

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

Constructor

Parameter	Type	Default	Description
width	number	1	Width of viewport
height	number	1	Height of viewport
latitude	number	0	Latitude of viewport center
longitude	number	0	Longitude of viewport center
zoom	number	11	Map zoom (scale is calculated as 2^zoom)
pitch	number	0	The pitch (tilt) of the map from the screen, in degrees (0 is straight down)
bearing	number	0	The bearing (rotation) of the map from north, in degrees counter-clockwise (0 means north is up)
fovy	number	see below	Field of view of camera in degrees
altitude	number	see below	Altitude of camera in screen units
position	number[]	null	Offset 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.

Parameter	Type	Default	Description
lngLatZ	Array	(required)	map coordinates, [lng, lat] or [lng, lat, Z] where Z is elevation in meters
options	Object	{}	named options
options.topLeft	Boolean	true	If 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.

Parameter	Type	Default	Description
xyz	Array	(required)	pixel coordinates, [x, y] or [x, y, z] where z is pixel depth
options	Object	{}	named options
options.topLeft	Boolean	true	If true projected coords are top left, otherwise bottom left
options.targetZ	number	0	If 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.

Parameter	Type	Default	Description
lngLat	Array	(required)	map coordinates, [lng, lat]
scale	number	this.scale	Web Mercator scale

Returns:

• [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

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