MercatorCoordinate

A `MercatorCoordinate` object represents a projected three dimensional position. `MercatorCoordinate` uses the web mercator projection ([EPSG:3857](https://epsg.io/3857)) with slightly different units: - the size of 1 unit is the width of the projected world instead of the "mercator meter" - the origin of the coordinate space is at the north-west corner instead of the middle. For example, `MercatorCoordinate(0, 0, 0)` is the north-west corner of the mercator world and `MercatorCoordinate(1, 1, 0)` is the south-east corner. If you are familiar with [vector tiles] of the coordinate space as the `0/0/0` tile with an extent of `1`. The `z` dimension of `MercatorCoordinate` is conformal. A cube in the mercator coordinate space would be rendered as a cube.

new SuperMap3D.MercatorCoordinate(x, y, z)

Name Type Description
x number The x component of the position.
y number The y component of the position.
z number The z component of the position.
Example:
const nullIsland = new mapboxgl.MercatorCoordinate(0.5, 0.5, 0);
See:
  • [Example: Add a custom style layer](https://www.mapbox.com/mapbox-gl-js/example/custom-style-layer/)

Methods

staticSuperMap3D.MercatorCoordinate.fromLngLat(lngLatLike, altitude) → MercatorCoordinate

Project a `LngLat` to a `MercatorCoordinate`.
Name Type Default Description
lngLatLike LngLatLike The location to project.
altitude number 0 The altitude in meters of the position.
Returns:
The projected mercator coordinate.
Example:
const coord = mapboxgl.MercatorCoordinate.fromLngLat({lng: 0, lat: 0}, 0);
console.log(coord); // MercatorCoordinate(0.5, 0.5, 0)

meterInMercatorCoordinateUnits() → number

Returns the distance of 1 meter in `MercatorCoordinate` units at this latitude. For coordinates in real world units using meters, this naturally provides the scale to transform into `MercatorCoordinate`s.
Returns:
Distance of 1 meter in `MercatorCoordinate` units.
Example:
// Calculate a new MercatorCoordinate that is 150 meters west of the other coord.
const coord = new mapboxgl.MercatorCoordinate(0.5, 0.25, 0);
const offsetInMeters = 150;
const offsetInMercatorCoordinateUnits = offsetInMeters * coord.meterInMercatorCoordinateUnits();
const westCoord = new mapboxgl.MercatorCoordinate(coord.x - offsetInMercatorCoordinateUnits, coord.y, coord.z);

toAltitude() → number

Returns the altitude in meters of the coordinate.
Returns:
The altitude in meters.
Example:
const coord = new mapboxgl.MercatorCoordinate(0, 0, 0.02);
coord.toAltitude(); // 6914.281956295339

toLngLat() → LngLat

Returns the `LngLat` for the coordinate.
Returns:
The `LngLat` object.
Example:
const coord = new mapboxgl.MercatorCoordinate(0.5, 0.5, 0);
const lngLat = coord.toLngLat(); // LngLat(0, 0)