Skip to content

Geography and geometry

General utilities and types that relate to working with and manipulating geographic information or geometries.

LngLat

A LngLat object represents a given longitude and latitude coordinate, measured in degrees. These coordinates are based on the WGS84 (EPSG:4326) standard.

vietmap GL uses longitude, latitude coordinate order (as opposed to latitude, longitude) to match the GeoJSON specification.

Note that any vietmap GL method that accepts a LngLat object as an argument or option can also accept an Array of two numbers and will perform an implicit conversion. This flexible type is documented as LngLatLike.

new LngLat(lng: number, lat: number)

Parameters

  • lng(number) Longitude, measured in degrees.

  • lat(number) Latitude, measured in degrees.

Example

var ll = new vietmapgl.LngLat(-123.9749, 40.7736);
ll.lng; // = -123.9749

Static Members

convert(input)

Converts an array of two numbers or an object with lng and lat or lon and lat properties to a LngLat object.

If a LngLat object is passed in, the function returns it unchanged.

Parameters

input(LngLatLike)An array of two numbers or object to convert, or a LngLat object to return.

Returns

LngLat: A new LngLat object, if a conversion occurred, or the original LngLat object.

Example

var arr = [-73.9749, 40.7736];
var ll = vietmapgl.LngLat.convert(arr);
ll;   // = LngLat {lng: -73.9749, lat: 40.7736}

Instance Members

distanceTo(lngLat)

Returns the approximate distance between a pair of coordinates in meters Uses the Haversine Formula (from R.W. Sinnott, "Virtues of the Haversine", Sky and Telescope, vol. 68, no. 2, 1984, p. 159)

Parameters

lngLat(LngLat)coordinates to compute the distance to

Returns

number: Distance in meters between the two coordinates.

Example

var new_york = new vietmapgl.LngLat(-74.0060, 40.7128);
var los_angeles = new vietmapgl.LngLat(-118.2437, 34.0522);
new_york.distanceTo(los_angeles); // = 3935751.690893987, "true distance" using a non-spherical approximation is ~3966km

toArray()

Returns the coordinates represented as an array of two numbers.

Returns

Array: The coordinates represeted as an array of longitude and latitude.

Example

var ll = new vietmapgl.LngLat(-73.9749, 40.7736);
ll.toArray(); // = [-73.9749, 40.7736]

toBounds(radius)

Returns a LngLatBounds from the coordinates extended by a given radius. The returned LngLatBounds completely contains the radius.

Parameters

radius(number)(default 0)Distance in meters from the coordinates to extend the bounds.

Returns

LngLatBounds: A new LngLatBounds object representing the coordinates extended by the radius .

Example

var ll = new vietmapgl.LngLat(-73.9749, 40.7736);
ll.toBounds(100).toArray(); // = [[-73.97501862141328, 40.77351016847229], [-73.97478137858673, 40.77368983152771]]

toString()

Returns the coordinates represent as a string.

Returns

string: The coordinates represented as a string of the format 'LngLat(lng, lat)' .

Example

var ll = new vietmapgl.LngLat(-73.9749, 40.7736);
ll.toString(); // = "LngLat(-73.9749, 40.7736)"

wrap()

Returns a new LngLat object whose longitude is wrapped to the range (-180, 180).

Returns

LngLat: The wrapped LngLat object.

Example

var ll = new vietmapgl.LngLat(286.0251, 40.7736);
var wrapped = ll.wrap();
wrapped.lng; // = -73.9749
  • Get coordinates of the mouse pointer
  • Display a popup
  • Create a timeline animation

LngLatLike

A LngLat object, an array of two numbers representing longitude and latitude, or an object with lng and lat or lon and lat properties.

Example

var v1 = new vietmapgl.LngLat(-122.420679, 37.772537);
var v2 = [-122.420679, 37.772537];
var v3 = {lon: -122.420679, lat: 37.772537};

LngLatBounds

A LngLatBounds object represents a geographical bounding box, defined by its southwest and northeast points in longitude and latitude.

If no arguments are provided to the constructor, a null bounding box is created.

Note that any Mapbox GL method that accepts a LngLatBounds object as an argument or option can also accept an Array of two LngLatLike constructs and will perform an implicit conversion. This flexible type is documented as LngLatBoundsLike.

new LngLatBounds(sw: LngLatLike?, ne: LngLatLike?)

Parameters

  • sw(LngLatLike?)The southwest corner of the bounding box.
  • ne(LngLatLike?)The northeast corner of the bounding box.

Example

var sw = new vietmapgl.LngLat(-73.9876, 40.7661);
var ne = new vietmapgl.LngLat(-73.9397, 40.8002);
var llb = new vietmapgl.LngLatBounds(sw, ne);

Static Members

convert(input)

Converts an array to a LngLatBounds object.

If a LngLatBounds object is passed in, the function returns it unchanged.

Internally, the function calls LngLat#convert to convert arrays to LngLat values.

Parameters

input(LngLatBoundsLike)An array of two coordinates to convert, or a LngLatBounds object to return.

Returns

LngLatBounds: A new LngLatBounds object, if a conversion occurred, or the original LngLatBounds object.

Example

var arr = [[-73.9876, 40.7661], [-73.9397, 40.8002]];
var llb = vietmapgl.LngLatBounds.convert(arr);
llb;   // = LngLatBounds {_sw: LngLat {lng: -73.9876, lat: 40.7661}, _ne: LngLat {lng: -73.9397, lat: 40.8002}}

Instance Members

contains(lnglat)

Check if the point is within the bounding box.

Parameters

lnglat(LngLatLike)geographic point to check against.

Returns

boolean: True if the point is within the bounding box.

Example

var llb = new vietmapgl.LngLatBounds(
  new vietmapgl.LngLat(-73.9876, 40.7661),
  new vietmapgl.LngLat(-73.9397, 40.8002)
);

var ll = new vietmapgl.LngLat(-73.9567, 40.7789);

console.log(llb.contains(ll)); // = true

extend(obj)

Extend the bounds to include a given LngLatLike or LngLatBoundsLike.

Parameters

obj((LngLatLike | LngLatBoundsLike))object to extend to

Returns

LngLatBounds: this

getCenter()

Returns the geographical coordinate equidistant from the bounding box's corners.

Returns

LngLat: The bounding box's center.

Example

var llb = new vietmapgl.LngLatBounds([-73.9876, 40.7661], [-73.9397, 40.8002]);
llb.getCenter(); // = LngLat {lng: -73.96365, lat: 40.78315}

getEast()

Returns the east edge of the bounding box.

Returns

number: The east edge of the bounding box.

getNorth()

Returns the north edge of the bounding box.

Returns

number: The north edge of the bounding box.

getNorthEast()

Returns the northeast corner of the bounding box.

Returns

LngLat: The northeast corner of the bounding box.

getNorthWest()

Returns the northwest corner of the bounding box.

Returns

LngLat: The northwest corner of the bounding box.

getSouth()

Returns the south edge of the bounding box.

Returns

number: The south edge of the bounding box.

getSouthEast()

Returns the southeast corner of the bounding box.

Returns

LngLat: The southeast corner of the bounding box.

getSouthWest()

Returns the southwest corner of the bounding box.

Returns

LngLat: The southwest corner of the bounding box.

getWest()

Returns the west edge of the bounding box.

Returns

number: The west edge of the bounding box.

isEmpty()

Check if the bounding box is an empty/null-type box.

Returns

boolean: True if bounds have been defined, otherwise false.

setNorthEast(ne)

Set the northeast corner of the bounding box

Parameters

ne(LngLatLike)a LngLatLike object describing the northeast corner of the bounding box.

Returns

LngLatBounds: this

setSouthWest(sw)

Set the southwest corner of the bounding box

Parameters

sw(LngLatLike)a LngLatLike object describing the southwest corner of the bounding box.

Returns

LngLatBounds: this

toArray()

Returns the bounding box represented as an array.

Returns

Array>: The bounding box represented as an array, consisting of the southwest and northeast coordinates of the bounding represented as arrays of numbers.

Example

var llb = new vietmapgl.LngLatBounds([-73.9876, 40.7661], [-73.9397, 40.8002]);
llb.toArray(); // = [[-73.9876, 40.7661], [-73.9397, 40.8002]]

toString()

Return the bounding box represented as a string.

Returns

string: The bounding box represents as a string of the format 'LngLatBounds(LngLat(lng, lat), LngLat(lng, lat))' .

Example

var llb = new vietmapgl.LngLatBounds([-73.9876, 40.7661], [-73.9397, 40.8002]);
llb.toString(); // = "LngLatBounds(LngLat(-73.9876, 40.7661), LngLat(-73.9397, 40.8002))"

LngLatBoundsLike

A LngLatBounds object, an array of LngLatLike objects in [sw, ne] order, or an array of numbers in [west, south, east, north] order.

Example

var v1 = new vietmapgl.LngLatBounds(
  new vietmapgl.LngLat(-73.9876, 40.7661),
  new vietmapgl.LngLat(-73.9397, 40.8002)
);
var v2 = new vietmapgl.LngLatBounds([-73.9876, 40.7661], [-73.9397, 40.8002])
var v3 = [[-73.9876, 40.7661], [-73.9397, 40.8002]];

PointLike

A Point or an array of two numbers representing x and y screen coordinates in pixels.

Example

var p1 = new Point(-77, 38); // a PointLike which is a Point
var p2 = [-77, 38]; // a PointLike which is an array of two numbers

MercatorCoordinate

A MercatorCoordinate object represents a projected three dimensional position.

MercatorCoordinate uses the web mercator projection (EPSG: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 it may be helpful to think 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 MercatorCoordinate(x: number, y: number, z: number)

Parameters

  • x(number)The x component of the position.
  • y(number)The y component of the position.
  • z(number)(default 0)The z component of the position.

Example

var nullIsland = new vietmapgl.MercatorCoordinate(0.5, 0.5, 0);

Static Members

fromLngLat(lngLatLike, altitude)

Project a LngLat to a MercatorCoordinate.

Parameters

  • lngLatLike(LngLatLike)The location to project.

  • altitude(number)(default 0)The altitude in meters of the position.

Returns

MercatorCoordinate: The projected mercator coordinate.

Example

var coord = vietmapgl.MercatorCoordinate.fromLngLat({ lng: 0, lat: 0}, 0);
coord; // MercatorCoordinate(0.5, 0.5, 0)

Instance Members

meterInMercatorCoordinateUnits()

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 MercatorCoordinates.

Returns

number: Distance of 1 meter in MercatorCoordinate units.

toAltitude()

Returns the altitude in meters of the coordinate.

Returns

number: The altitude in meters.

Example

var coord = new vietmapgl.MercatorCoordinate(0, 0, 0.02);
coord.toAltitude(); // 6914.281956295339

toLngLat()

Returns the LngLat for the coordinate.

Returns

LngLat: The LngLat object.

Example

var coord = new vietmapgl.MercatorCoordinate(0.5, 0.5, 0);
var lngLat = coord.toLngLat(); // LngLat(0, 0)
  • Add a custom style layer

EdgeInsets

An EdgeInset object represents screen space padding applied to the edges of the viewport. This shifts the apprent center or the vanishing point of the map. This is useful for adding floating UI elements on top of the map and having the vanishing point shift as UI elements resize.

new EdgeInsets(top: number, bottom: number, left: number, right: number)

Parameters

  • top(number)(default 0)
  • bottom(number)(default 0)
  • left(number)(default 0)
  • right(number)(default 0)

Static Members

getCenter(width, height)

Utility method that computes the new apprent center or vanishing point after applying insets. This is in pixels and with the top left being (0.0) and +y being downwards.

Parameters

  • width(number)the width
  • height(number)the height

Returns

Point: the point

interpolate(start, target, t)

Interpolates the inset in-place. This maintains the current inset value for any inset not present in target.

Parameters

  • start((PaddingOptions | EdgeInsets))interpolation start

  • target(PaddingOptions)interpolation target

  • t(number)interpolation step/weight

Returns

EdgeInsets: the insets

toJSON()

Returns the current state as json, useful when you want to have a read-only representation of the inset.

Returns

PaddingOptions: state as json