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.
Goong GL uses longitude, latitude coordinate order (as opposed to latitude, longitude) to match GeoJSON.
Note that any Goong 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 goongjs.LngLat(-73.9749, 40.7736);
static Members
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 = goongjs.LngLat.convert(arr);
ll; // = LngLat {lng: -73.9749, lat: 40.7736}
Instance Members
Returns the coordinates represented as an array of two numbers.
Returns
Array<number>: The coordinates represeted as an array of longitude and latitude.
Example
var ll = new goongjs.LngLat(-73.9749, 40.7736);
ll.toArray(); // = [-73.9749, 40.7736]
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 goongjs.LngLat(-73.9749, 40.7736);
ll.toBounds(100).toArray(); // = [[-73.97501862141328, 40.77351016847229], [-73.97478137858673, 40.77368983152771]]
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 goongjs.LngLat(-73.9749, 40.7736);
ll.toString(); // = "LngLat(-73.9749, 40.7736)"
Returns a new LngLat object whose longitude is wrapped to the range (-180, 180).
Returns
(LngLat) The wrapped LngLat object.
Example
var ll = new goongjs.LngLat(286.0251, 40.7736);
var wrapped = ll.wrap();
wrapped.lng; // = -73.9749
Related
- Get coordinates of the mouse pointer
- Display a popup
- Highlight features within a bounding box
- 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 goongjs.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 goongjs.LngLat(-73.9876, 40.7661);
var ne = new goongjs.LngLat(-73.9397, 40.8002);
var llb = new goongjs.LngLatBounds(sw, ne);
static Members
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 = goongjs.LngLatBounds.convert(arr);
llb; // = LngLatBounds {_sw: LngLat {lng: -73.9876, lat: 40.7661}, _ne: LngLat {lng: -73.9397, lat: 40.8002}}
Instance Members
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.
Extend the bounds to include a given LngLat or LngLatBounds.
Parameters
obj ((LngLat|LngLatBounds))object to extend to
Returns
LngLatBounds: this
Returns the geographical coordinate equidistant from the bounding box's corners.
Returns
(LngLat) The bounding box's center.
Example
var llb = new goongjs.LngLatBounds([-73.9876, 40.7661], [-73.9397, 40.8002]);
llb.getCenter(); // = LngLat {lng: -73.96365, lat: 40.78315}
Returns the northeast corner of the bounding box.
Returns
(LngLat) The northeast corner of the bounding box.
Returns the northwest corner of the bounding box.
Returns
(LngLat) The northwest corner of the bounding box.
Returns the southeast corner of the bounding box.
Returns
(LngLat) The southeast corner of the bounding box.
Returns the southwest corner of the bounding box.
Returns
(LngLat) The southwest corner of the bounding box.
Check if the bounding box is an empty/null-type box.
Returns
boolean: True if bounds have been defined, otherwise false.
Returns the bounding box represented as an array.
Returns
Array<Array<number>>: 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 goongjs.LngLatBounds([-73.9876, 40.7661], [-73.9397, 40.8002]);
llb.toArray(); // = [[-73.9876, 40.7661], [-73.9397, 40.8002]]
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 goongjs.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 goongjs.LngLatBounds(
new goongjs.LngLat(-73.9876, 40.7661),
new goongjs.LngLat(-73.9397, 40.8002)
);
var v2 = new goongjs.LngLatBounds([-73.9876, 40.7661], [-73.9397, 40.8002])
var v3 = [[-73.9876, 40.7661], [-73.9397, 40.8002]];
Point
A Point geometry object, which has x and y properties representing screen coordinates in pixels.
PointLike
A Point or an array of two numbers representing x and y screen coordinates in pixels.
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 andMercatorCoordinate(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 of1.
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 goongjs.MercatorCoordinate(0.5, 0.5, 0);
static Members
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 = goongjs.MercatorCoordinate.fromLngLat({ lng: 0, lat: 0}, 0);
coord; // MercatorCoordinate(0.5, 0.5, 0)
Instance Members
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.
Returns the altitude in meters of the coordinate.
Returns
number: The altitude in meters.
Example
var coord = new goongjs.MercatorCoordinate(0, 0, 0.02);
coord.toAltitude(); // 6914.281956295339
Returns the LngLat for the coordinate.
Returns
(LngLat) The LngLat object.
Example
var coord = new goongjs.MercatorCoordinate(0.5, 0.5, 0);
var latLng = coord.toLngLat(); // LngLat(0, 0)