UNPKG

leaflet

Version:

JavaScript library for mobile-friendly interactive maps

222 lines (200 loc) • 6.47 kB
import * as Util from '../core/Util.js'; import {LatLngBounds} from './LatLngBounds.js'; /** @typedef {[number, number, number?]} LatLngTuple */ /** * A geographical point as a plain object. * @typedef {Object} LatLngLiteral * @property {number} lat Latitude in degrees. * @property {number} lng Longitude in degrees. * @property {number} [alt] Altitude in meters. */ /** * A `LatLng`, or its array (`[lat, lng]`, `[lat, lng, alt]`) or object (`{lat, lng}`, `{lat, lon}`) form. * @typedef {LatLng | LatLngTuple | LatLngLiteral | {lat: number, lon: number, alt?: number}} LatLngExpression */ /** * Represents a geographical point with a certain latitude and longitude. * * @example * ```js * const latlng = new LatLng(50.5, 30.5); * ``` * * All Leaflet methods that accept LatLng objects also accept them in a simple Array form and simple object form * (unless noted otherwise), so these lines are equivalent: * * ```js * map.panTo([50, 30]); * map.panTo({lat: 50, lng: 30}); * map.panTo({lat: 50, lon: 30}); * map.panTo(new LatLng(50, 30)); * ``` * * Note that `LatLng` does not inherit from Leaflet's `Class` object, which means new classes can't inherit from it, * and new methods can't be added to it with the `include` function. * * @categoryDescription Functions * There are several static functions which can be called without instantiating LatLng: */ export class LatLng { /** * Creates an object representing a geographical point with the given latitude and longitude (and optionally * altitude). * @overload * @param {number} lat * @param {number} lng * @param {number} [alt] */ /** * Expects an array of the form `[Number, Number]` or `[Number, Number, Number]`, or a plain object of the form * `{lat: Number, lng: Number}` or `{lat: Number, lng: Number, alt: Number}` instead. You can also use `lon` in * place of `lng` in the object form. * @overload * @param {LatLngExpression} coords */ /** * @param {any} lat * @param {number} [lng] * @param {number} [alt] */ constructor(lat, lng, alt) { if (lat instanceof LatLng) { // We can use the same object, no need to clone it // eslint-disable-next-line no-constructor-return return lat; } let _lat = lat, _lng = lng, _alt = alt; if (Array.isArray(lat)) { _lat = lat.length <= 3 ? lat[0] : NaN; _lng = lat[1]; _alt = lat[2]; } else if (typeof lat === 'object' && lat !== null) { _lat = lat.lat; _lng = 'lng' in lat ? lat.lng : lat.lon; _alt = lat.alt; } /** * Latitude in degrees * @type {number} */ this.lat = Util.toNumber(_lat); /** * Longitude in degrees * @type {number} */ this.lng = Util.toNumber(_lng); if (isNaN(this.lat) || isNaN(this.lng)) { throw new Error(`Invalid LatLng object: (${_lat}, ${_lng})`); } if (_alt != null) { /** * Altitude in meters (optional) * @type {number | undefined} */ this.alt = Util.toNumber(_alt); if (isNaN(this.alt)) { throw new Error(`Invalid LatLng altitude: ${_alt}`); } } } /** * Returns `true` if the LatLng object can be properly initialized. * @category Functions * @overload * @param {number} lat * @param {number} [lng] * @param {number} [alt] * @returns {boolean} */ /** * Expects an array of the form `[Number, Number]` or `[Number, Number, Number]`, or a plain object of the form * `{lat: Number, lng: Number}`. Returns `true` if the LatLng object can be properly initialized. * @overload * @param {LatLngExpression} coords * @returns {boolean} */ /** * @param {any} lat * @param {any} [lng] * @param {any} [alt] */ static validate(lat, lng, alt) { try { return !!new LatLng(lat, lng, alt); } catch { return false; } } /** * Returns `true` if the given `LatLng` point is at the same position (within a small margin of * error). The margin of error can be overridden by setting `maxMargin` to a small number. * @param {LatLngExpression} [obj] * @param {number} [maxMargin] */ equals(obj, maxMargin) { if (!obj) { return false; } obj = new LatLng(obj); const margin = Math.max( Math.abs(this.lat - obj.lat), Math.abs(this.lng - obj.lng)); return margin <= (maxMargin ?? 1.0E-9); } /** * Returns a string representation of the point (for debugging purposes). * @param {number} [precision] */ toString(precision) { return `LatLng(${Util.formatNum(this.lat, precision)}, ${Util.formatNum(this.lng, precision)})`; } /** * Returns the distance (in meters) to the given `LatLng` calculated using the * [Haversine formula](https://en.wikipedia.org/wiki/Haversine_formula). * @param {LatLngExpression} other */ distanceTo(other) { return haversineDistance(this, new LatLng(other), 6371000); } /** Returns a new `LatLng` object with the longitude wrapped so it's always between -180 and +180 degrees. */ wrap() { return new LatLng(this.lat, Util.wrapNum(this.lng, [-180, 180], true), this.alt); } /** * Returns a new `LatLngBounds` object in which each boundary is `sizeInMeters/2` meters apart from the `LatLng`. * @param {number} sizeInMeters */ toBounds(sizeInMeters) { const latAccuracy = 180 * sizeInMeters / 40075017, lngAccuracy = latAccuracy / Math.cos((Math.PI / 180) * this.lat); return new LatLngBounds( [this.lat - latAccuracy, this.lng - lngAccuracy], [this.lat + latAccuracy, this.lng + lngAccuracy]); } /** Returns a copy of the current LatLng. */ clone() { // to skip the validation in the constructor we need to initialize with 0 and then set the values later const latlng = new LatLng(0, 0); latlng.lat = this.lat; latlng.lng = this.lng; if (this.alt !== undefined) { latlng.alt = this.alt; } return latlng; } }; /** * Great-circle distance on a sphere of radius R, shared with `EarthCRS.distance`. * @param {LatLng} latlng1 * @param {LatLng} latlng2 * @param {number} R */ export function haversineDistance(latlng1, latlng2, R) { const rad = Math.PI / 180, lat1 = latlng1.lat * rad, lat2 = latlng2.lat * rad, sinDLat = Math.sin((latlng2.lat - latlng1.lat) * rad / 2), sinDLon = Math.sin((latlng2.lng - latlng1.lng) * rad / 2), // clamp, since rounding can push this slightly above 1 for antipodal points and make `sqrt(1 - a)` NaN a = Math.min(sinDLat * sinDLat + Math.cos(lat1) * Math.cos(lat2) * sinDLon * sinDLon, 1), c = 2 * Math.atan2(Math.sqrt(a), Math.sqrt(1 - a)); return R * c; }