The WebMercatorViewport
class enables 3D rendering to seamlessly overlay on top of map components that take web mercator style map coordinates (latitude
, lon
, zoom
, pitch
, bearing
etc).
When in perspective mode, the WebMercatorViewport
is carefully tuned to work in synchronization with mapbox-gl
's projection matrix.
For more information consult the Viewports article.
The WebMercatorViewport
is the default viewport for deck.gl. If you are using the DeckGL
React component you may not even need to instantiate it explicitly.
import DeckGL from 'deck.gl';
<DeckGL width={width} heigh={height} longitude={longitude} latitude={latitude} zoom={zoom} pitch={pitch} bearing={bearing} layers=[...]/>
Is equivalent to
import DeckGL, {WebMercatorViewport} from 'deck.gl';
const viewport = new WebMercatorViewport({width, height, longitude, latitude, zoom, pitch, bearing});
<DeckGL views={[viewport]} layers=[...]/>
new WebMercatorViewport({width, height, longitude, latitude, zoom, pitch, bearing});
Parameters:
-
opts
(Object) - Web Mercator viewport optionswidth
(Number) - Width of "viewport" or window. Default to1
.height
(Number) - Height of "viewport" or window. Default to1
.
web mercator style arguments:
latitude
(Number, optional) - Center of viewport on map (alternative to center). Default to37
.longitude
(Number, optional) - Center of viewport on map (alternative to center). Default to-122
.zoom
(Number, optional) -center
. Default to11
.pitch
(Number, optional) - Camera angle in degrees (0 is straight down). Default to0
.bearing
(Number, optional) - Map rotation in degrees (0 means north is up). Default to0
.altitude
(Number, optional) - Altitude of camera in screen units. Default to1.5
.
projection matrix arguments:
farZMultiplier
(Number, optional) - Default to10
.
Remarks:
altitude
has a default value that matches assumptions in mapbox-glwidth
andheight
are forced to 1 if supplied as 0, to avoid division by zero. This is intended to reduce the burden of apps to check values before instantiating aViewport
.- When using Mercator projection, per cartographic tradition, longitudes and latitudes are specified as degrees.
Inherits all Viewport methods.
Project [longitude, latitude]
on sphere onto "screen pixel" coordinates [x, y]
without
considering any perspective (effectively ignoring pitch, bearing and altitude).
Parameters:
coordinates
(Array) -[longitude, latitude]
coordinates.scale
(Number) - Map zoom scale calculated fromMath.pow(2, zoom)
.
Returns:
- Screen coordinates in
[x, y]
.
Unprojects a screen coordinate [x, y]
to [longitude, latitude]
on sphere without
considering any perspective (effectively ignoring pitch, bearing and altitude).
Parameters:
pixels
(Array) -[x, y]
scale
(Number) - Map zoom scale calculated fromMath.pow(2, zoom)
.
Returns:
- Map or world coordinates in
[longitude, latitude]
.
Returns:
- An object with precalculated distance scales allowing conversion between lnglat deltas, meters and pixels.
Remarks:
- The returned scales represent simple linear approximations of the local Web Mercator projection scale around the viewport center. Error increases with distance from viewport center (Very roughly 1% per 100km).
- When converting numbers to 32 bit floats (e.g. for use in WebGL shaders) distance offsets can sometimes be used to gain additional computational precision, which can greatly outweigh the small linear approximation error mentioned above.
Converts a meter offset to a lnglat offset using linear approximation.
For information on numerical precision, see remarks on getDistanceScales
.
Parameters:
xyz
(Array) - Array of[x, y, z]
in meter deltas. Passing az
is optional.
Returns:
- Array of deltas in
[longitude, latitude]
or[longitude, latitude, altitude]
ifz
is provided.
Converts a lnglat offset to a meter offset using linear approximation.
For information on numerical precision, see remarks on
getDistanceScales
.
Parameters:
deltaLngLatZ
- Array of[longitude, latitude, altitude]
deltas. Passing aaltitude
is optional.
Returns:
- Array of meter deltas in
[x, y]
or[x, y, z]
ifaltitude
is provided.
Add a meter delta to a base lnglat coordinate using linear approximation.
For information on numerical precision, see remarks on
getDistanceScales
.
Parameters:
lngLatZ
(Array) - Base coordinate in[longitude, latitude, altitude]
. Passing aaltitude
is optional.xyz
(Array) - Array of[x, y, z]
in meter deltas. Passing az
is optional.
Returns:
- New coordinate array in
[longitude, latitude]
or[longitude, latitude, altitude]
ifz
is provided.
- Because
WebMercatorViewport
a subclass ofViewport
, an application can implement support for generic 3DViewport
s and automatically get the ability to accept web mercator style map coordinates. - A limitation at the moment is that there is no way to extract web mercator parameters from a "generic" viewport, so for map synchronization applications (rendering on top of a typical map component that only accepts web mercator parameters) the
WebMercatorViewport
is necessary. - Facilitates the necessary mercator projections by breaking them into a minimal non-linear piece followed by a standard projection chain.
- Making deck.gl work with non-mapbox map systems in perspective mode might require subclassing
WebMercatorViewport
and adjust the projection so it matches the map's projection.