@antv/l7-map 2.25.7 → 2.25.9

package/lib/map/geo/lng_lat_bounds.js

@@ -0,0 +1,341 @@
+"use strict";
+
+var _interopRequireDefault = require("@babel/runtime/helpers/interopRequireDefault");
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.LngLatBounds = void 0;
+var _defineProperty2 = _interopRequireDefault(require("@babel/runtime/helpers/defineProperty"));
+var _lng_lat = require("./lng_lat");
+/**
+ * A {@link LngLatBounds} object, an array of {@link LngLatLike} objects in [sw, ne] order,
+ * or an array of numbers in [west, south, east, north] order.
+ *
+ * @group Geography and Geometry
+ *
+ * @example
+ * ```ts
+ * let v1 = new LngLatBounds(
+ *   new LngLat(-73.9876, 40.7661),
+ *   new LngLat(-73.9397, 40.8002)
+ * );
+ * let v2 = new LngLatBounds([-73.9876, 40.7661], [-73.9397, 40.8002])
+ * let v3 = [[-73.9876, 40.7661], [-73.9397, 40.8002]];
+ * ```
+ */
+
+/**
+ * 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 {@link LngLatLike} constructs and will perform an implicit conversion.
+ * This flexible type is documented as {@link LngLatBoundsLike}.
+ *
+ * @group Geography and Geometry
+ *
+ * @example
+ * ```ts
+ * let sw = new LngLat(-73.9876, 40.7661);
+ * let ne = new LngLat(-73.9397, 40.8002);
+ * let llb = new LngLatBounds(sw, ne);
+ * ```
+ */
+class LngLatBounds {
+  /**
+   * @param sw - The southwest corner of the bounding box.
+   * OR array of 4 numbers in the order of  west, south, east, north
+   * OR array of 2 LngLatLike: [sw,ne]
+   * @param ne - The northeast corner of the bounding box.
+   * @example
+   * ```ts
+   * let sw = new LngLat(-73.9876, 40.7661);
+   * let ne = new LngLat(-73.9397, 40.8002);
+   * let llb = new LngLatBounds(sw, ne);
+   * ```
+   * OR
+   * ```ts
+   * let llb = new LngLatBounds([-73.9876, 40.7661, -73.9397, 40.8002]);
+   * ```
+   * OR
+   * ```ts
+   * let llb = new LngLatBounds([sw, ne]);
+   * ```
+   */
+  constructor(sw, ne) {
+    (0, _defineProperty2.default)(this, "_ne", void 0);
+    (0, _defineProperty2.default)(this, "_sw", void 0);
+    if (!sw) {
+      // noop
+    } else if (ne) {
+      this.setSouthWest(sw).setNorthEast(ne);
+    } else if (Array.isArray(sw)) {
+      if (sw.length === 4) {
+        // 4 element array: west, south, east, north
+        this.setSouthWest([sw[0], sw[1]]).setNorthEast([sw[2], sw[3]]);
+      } else {
+        this.setSouthWest(sw[0]).setNorthEast(sw[1]);
+      }
+    }
+  }
+
+  /**
+   * Set the northeast corner of the bounding box
+   *
+   * @param ne - a {@link LngLatLike} object describing the northeast corner of the bounding box.
+   */
+  setNorthEast(ne) {
+    this._ne = ne instanceof _lng_lat.LngLat ? new _lng_lat.LngLat(ne.lng, ne.lat) : _lng_lat.LngLat.convert(ne);
+    return this;
+  }
+
+  /**
+   * Set the southwest corner of the bounding box
+   *
+   * @param sw - a {@link LngLatLike} object describing the southwest corner of the bounding box.
+   */
+  setSouthWest(sw) {
+    this._sw = sw instanceof _lng_lat.LngLat ? new _lng_lat.LngLat(sw.lng, sw.lat) : _lng_lat.LngLat.convert(sw);
+    return this;
+  }
+
+  /**
+   * Extend the bounds to include a given LngLatLike or LngLatBoundsLike.
+   *
+   * @param obj - object to extend to
+   */
+  extend(obj) {
+    const sw = this._sw,
+      ne = this._ne;
+    let sw2, ne2;
+    if (obj instanceof _lng_lat.LngLat) {
+      sw2 = obj;
+      ne2 = obj;
+    } else if (obj instanceof LngLatBounds) {
+      sw2 = obj._sw;
+      ne2 = obj._ne;
+      if (!sw2 || !ne2) return this;
+    } else {
+      if (Array.isArray(obj)) {
+        if (obj.length === 4 || obj.every(Array.isArray)) {
+          const lngLatBoundsObj = obj;
+          return this.extend(LngLatBounds.convert(lngLatBoundsObj));
+        } else {
+          const lngLatObj = obj;
+          return this.extend(_lng_lat.LngLat.convert(lngLatObj));
+        }
+      } else if (obj && ('lng' in obj || 'lon' in obj) && 'lat' in obj) {
+        return this.extend(_lng_lat.LngLat.convert(obj));
+      }
+      return this;
+    }
+    if (!sw && !ne) {
+      this._sw = new _lng_lat.LngLat(sw2.lng, sw2.lat);
+      this._ne = new _lng_lat.LngLat(ne2.lng, ne2.lat);
+    } else {
+      sw.lng = Math.min(sw2.lng, sw.lng);
+      sw.lat = Math.min(sw2.lat, sw.lat);
+      ne.lng = Math.max(ne2.lng, ne.lng);
+      ne.lat = Math.max(ne2.lat, ne.lat);
+    }
+    return this;
+  }
+
+  /**
+   * Returns the geographical coordinate equidistant from the bounding box's corners.
+   *
+   * @returns The bounding box's center.
+   * @example
+   * ```ts
+   * let llb = new LngLatBounds([-73.9876, 40.7661], [-73.9397, 40.8002]);
+   * llb.getCenter(); // = LngLat {lng: -73.96365, lat: 40.78315}
+   * ```
+   */
+  getCenter() {
+    return new _lng_lat.LngLat((this._sw.lng + this._ne.lng) / 2, (this._sw.lat + this._ne.lat) / 2);
+  }
+
+  /**
+   * Returns the southwest corner of the bounding box.
+   *
+   * @returns The southwest corner of the bounding box.
+   */
+  getSouthWest() {
+    return this._sw;
+  }
+
+  /**
+   * Returns the northeast corner of the bounding box.
+   *
+   * @returns The northeast corner of the bounding box.
+   */
+  getNorthEast() {
+    return this._ne;
+  }
+
+  /**
+   * Returns the northwest corner of the bounding box.
+   *
+   * @returns The northwest corner of the bounding box.
+   */
+  getNorthWest() {
+    return new _lng_lat.LngLat(this.getWest(), this.getNorth());
+  }
+
+  /**
+   * Returns the southeast corner of the bounding box.
+   *
+   * @returns The southeast corner of the bounding box.
+   */
+  getSouthEast() {
+    return new _lng_lat.LngLat(this.getEast(), this.getSouth());
+  }
+
+  /**
+   * Returns the west edge of the bounding box.
+   *
+   * @returns The west edge of the bounding box.
+   */
+  getWest() {
+    return this._sw.lng;
+  }
+
+  /**
+   * Returns the south edge of the bounding box.
+   *
+   * @returns The south edge of the bounding box.
+   */
+  getSouth() {
+    return this._sw.lat;
+  }
+
+  /**
+   * Returns the east edge of the bounding box.
+   *
+   * @returns The east edge of the bounding box.
+   */
+  getEast() {
+    return this._ne.lng;
+  }
+
+  /**
+   * Returns the north edge of the bounding box.
+   *
+   * @returns The north edge of the bounding box.
+   */
+  getNorth() {
+    return this._ne.lat;
+  }
+
+  /**
+   * Returns the bounding box represented as an array.
+   *
+   * @returns The bounding box represented as an array, consisting of the
+   * southwest and northeast coordinates of the bounding represented as arrays of numbers.
+   * @example
+   * ```ts
+   * let llb = new LngLatBounds([-73.9876, 40.7661], [-73.9397, 40.8002]);
+   * llb.toArray(); // = [[-73.9876, 40.7661], [-73.9397, 40.8002]]
+   * ```
+   */
+  toArray() {
+    return [this._sw.toArray(), this._ne.toArray()];
+  }
+
+  /**
+   * Return the bounding box represented as a string.
+   *
+   * @returns The bounding box represents as a string of the format
+   * `'LngLatBounds(LngLat(lng, lat), LngLat(lng, lat))'`.
+   * @example
+   * ```ts
+   * let llb = new LngLatBounds([-73.9876, 40.7661], [-73.9397, 40.8002]);
+   * llb.toString(); // = "LngLatBounds(LngLat(-73.9876, 40.7661), LngLat(-73.9397, 40.8002))"
+   * ```
+   */
+  toString() {
+    return `LngLatBounds(${this._sw.toString()}, ${this._ne.toString()})`;
+  }
+
+  /**
+   * Check if the bounding box is an empty/`null`-type box.
+   *
+   * @returns True if bounds have been defined, otherwise false.
+   */
+  isEmpty() {
+    return !(this._sw && this._ne);
+  }
+
+  /**
+   * Check if the point is within the bounding box.
+   *
+   * @param lnglat - geographic point to check against.
+   * @returns `true` if the point is within the bounding box.
+   * @example
+   * ```ts
+   * let llb = new LngLatBounds(
+   *   new LngLat(-73.9876, 40.7661),
+   *   new LngLat(-73.9397, 40.8002)
+   * );
+   *
+   * let ll = new LngLat(-73.9567, 40.7789);
+   *
+   * console.log(llb.contains(ll)); // = true
+   * ```
+   */
+  contains(lnglat) {
+    const {
+      lng,
+      lat
+    } = _lng_lat.LngLat.convert(lnglat);
+    const containsLatitude = this._sw.lat <= lat && lat <= this._ne.lat;
+    let containsLongitude = this._sw.lng <= lng && lng <= this._ne.lng;
+    if (this._sw.lng > this._ne.lng) {
+      // wrapped coordinates
+      containsLongitude = this._sw.lng >= lng && lng >= this._ne.lng;
+    }
+    return containsLatitude && containsLongitude;
+  }
+
+  /**
+   * 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.
+   *
+   * @param input - An array of two coordinates to convert, or a `LngLatBounds` object to return.
+   * @returns A new `LngLatBounds` object, if a conversion occurred, or the original `LngLatBounds` object.
+   * @example
+   * ```ts
+   * let arr = [[-73.9876, 40.7661], [-73.9397, 40.8002]];
+   * let llb = LngLatBounds.convert(arr); // = LngLatBounds {_sw: LngLat {lng: -73.9876, lat: 40.7661}, _ne: LngLat {lng: -73.9397, lat: 40.8002}}
+   * ```
+   */
+  static convert(input) {
+    if (input instanceof LngLatBounds) return input;
+    return new LngLatBounds(input);
+  }
+
+  /**
+   * Returns a `LngLatBounds` from the coordinates extended by a given `radius`. The returned `LngLatBounds` completely contains the `radius`.
+   *
+   * @param center - center coordinates of the new bounds.
+   * @param radius - Distance in meters from the coordinates to extend the bounds.
+   * @returns A new `LngLatBounds` object representing the coordinates extended by the `radius`.
+   * @example
+   * ```ts
+   * let center = new LngLat(-73.9749, 40.7736);
+   * LngLatBounds.fromLngLat(100).toArray(); // = [[-73.97501862141328, 40.77351016847229], [-73.97478137858673, 40.77368983152771]]
+   * ```
+   */
+  static fromLngLat(center, radius = 0) {
+    const earthCircumferenceInMetersAtEquator = 40075017;
+    const latAccuracy = 360 * radius / earthCircumferenceInMetersAtEquator,
+      lngAccuracy = latAccuracy / Math.cos(Math.PI / 180 * center.lat);
+    return new LngLatBounds(new _lng_lat.LngLat(center.lng - lngAccuracy, center.lat - latAccuracy), new _lng_lat.LngLat(center.lng + lngAccuracy, center.lat + latAccuracy));
+  }
+}
+exports.LngLatBounds = LngLatBounds;

package/lib/map/geo/mercator_coordinate.d.ts

@@ -0,0 +1,113 @@
+import type { LngLatLike } from './lng_lat';
+import { LngLat } from './lng_lat';
+interface ILngLat {
+    lng: number;
+    lat: number;
+    wrap(): ILngLat;
+    toArray(): [number, number];
+    distanceTo(lngLat: ILngLat): number;
+    toString(): string;
+}
+interface IMercatorCoordinate {
+    x: number;
+    y: number;
+    z: number;
+    toLngLat(): ILngLat;
+    toAltitude(): number;
+    meterInMercatorCoordinateUnits(): number;
+}
+export declare function mercatorXfromLng(lng: number): number;
+export declare function mercatorYfromLat(lat: number): number;
+export declare function mercatorZfromAltitude(altitude: number, lat: number): number;
+export declare function lngFromMercatorX(x: number): number;
+export declare function latFromMercatorY(y: number): number;
+export declare function altitudeFromMercatorZ(z: number, y: number): number;
+/**
+ * Determine the Mercator scale factor for a given latitude, see
+ * https://en.wikipedia.org/wiki/Mercator_projection#Scale_factor
+ *
+ * At the equator the scale factor will be 1, which increases at higher latitudes.
+ *
+ * @param lat - Latitude
+ * @returns scale factor
+ */
+export declare function mercatorScale(lat: number): number;
+/**
+ * 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](https://github.com/mapbox/vector-tile-spec) 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.
+ *
+ * @group Geography and Geometry
+ *
+ * @example
+ * ```ts
+ * let nullIsland = new MercatorCoordinate(0.5, 0.5, 0);
+ * ```
+ * @see [Add a custom style layer](https://maplibre.org/maplibre-gl-js/docs/examples/custom-style-layer/)
+ */
+export declare class MercatorCoordinate implements IMercatorCoordinate {
+    x: number;
+    y: number;
+    z: number;
+    /**
+     * @param x - The x component of the position.
+     * @param y - The y component of the position.
+     * @param z - The z component of the position.
+     */
+    constructor(x: number, y: number, z?: number);
+    /**
+     * Project a `LngLat` to a `MercatorCoordinate`.
+     *
+     * @param lngLatLike - The location to project.
+     * @param altitude - The altitude in meters of the position.
+     * @returns The projected mercator coordinate.
+     * @example
+     * ```ts
+     * let coord = MercatorCoordinate.fromLngLat({ lng: 0, lat: 0}, 0);
+     * coord; // MercatorCoordinate(0.5, 0.5, 0)
+     * ```
+     */
+    static fromLngLat(lngLatLike: LngLatLike, altitude?: number): MercatorCoordinate;
+    /**
+     * Returns the `LngLat` for the coordinate.
+     *
+     * @returns The `LngLat` object.
+     * @example
+     * ```ts
+     * let coord = new MercatorCoordinate(0.5, 0.5, 0);
+     * let lngLat = coord.toLngLat(); // LngLat(0, 0)
+     * ```
+     */
+    toLngLat(): LngLat;
+    /**
+     * Returns the altitude in meters of the coordinate.
+     *
+     * @returns The altitude in meters.
+     * @example
+     * ```ts
+     * let coord = new MercatorCoordinate(0, 0, 0.02);
+     * coord.toAltitude(); // 6914.281956295339
+     * ```
+     */
+    toAltitude(): 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.
+     */
+    meterInMercatorCoordinateUnits(): number;
+}
+export {};

package/lib/map/geo/mercator_coordinate.js

@@ -0,0 +1,157 @@
+"use strict";
+
+var _interopRequireDefault = require("@babel/runtime/helpers/interopRequireDefault");
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.MercatorCoordinate = void 0;
+exports.altitudeFromMercatorZ = altitudeFromMercatorZ;
+exports.latFromMercatorY = latFromMercatorY;
+exports.lngFromMercatorX = lngFromMercatorX;
+exports.mercatorScale = mercatorScale;
+exports.mercatorXfromLng = mercatorXfromLng;
+exports.mercatorYfromLat = mercatorYfromLat;
+exports.mercatorZfromAltitude = mercatorZfromAltitude;
+var _defineProperty2 = _interopRequireDefault(require("@babel/runtime/helpers/defineProperty"));
+var _lng_lat = require("./lng_lat");
+/*
+ * The average circumference of the world in meters.
+ */
+const earthCircumfrence = 2 * Math.PI * _lng_lat.earthRadius; // meters
+
+/*
+ * The circumference at a line of latitude in meters.
+ */
+function circumferenceAtLatitude(latitude) {
+  return earthCircumfrence * Math.cos(latitude * Math.PI / 180);
+}
+function mercatorXfromLng(lng) {
+  return (180 + lng) / 360;
+}
+function mercatorYfromLat(lat) {
+  return (180 - 180 / Math.PI * Math.log(Math.tan(Math.PI / 4 + lat * Math.PI / 360))) / 360;
+}
+function mercatorZfromAltitude(altitude, lat) {
+  return altitude / circumferenceAtLatitude(lat);
+}
+function lngFromMercatorX(x) {
+  return x * 360 - 180;
+}
+function latFromMercatorY(y) {
+  const y2 = 180 - y * 360;
+  return 360 / Math.PI * Math.atan(Math.exp(y2 * Math.PI / 180)) - 90;
+}
+function altitudeFromMercatorZ(z, y) {
+  return z * circumferenceAtLatitude(latFromMercatorY(y));
+}
+
+/**
+ * Determine the Mercator scale factor for a given latitude, see
+ * https://en.wikipedia.org/wiki/Mercator_projection#Scale_factor
+ *
+ * At the equator the scale factor will be 1, which increases at higher latitudes.
+ *
+ * @param lat - Latitude
+ * @returns scale factor
+ */
+function mercatorScale(lat) {
+  return 1 / Math.cos(lat * Math.PI / 180);
+}
+
+/**
+ * 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](https://github.com/mapbox/vector-tile-spec) 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.
+ *
+ * @group Geography and Geometry
+ *
+ * @example
+ * ```ts
+ * let nullIsland = new MercatorCoordinate(0.5, 0.5, 0);
+ * ```
+ * @see [Add a custom style layer](https://maplibre.org/maplibre-gl-js/docs/examples/custom-style-layer/)
+ */
+class MercatorCoordinate {
+  /**
+   * @param x - The x component of the position.
+   * @param y - The y component of the position.
+   * @param z - The z component of the position.
+   */
+  constructor(x, y, z = 0) {
+    (0, _defineProperty2.default)(this, "x", void 0);
+    (0, _defineProperty2.default)(this, "y", void 0);
+    (0, _defineProperty2.default)(this, "z", void 0);
+    this.x = +x;
+    this.y = +y;
+    this.z = +z;
+  }
+
+  /**
+   * Project a `LngLat` to a `MercatorCoordinate`.
+   *
+   * @param lngLatLike - The location to project.
+   * @param altitude - The altitude in meters of the position.
+   * @returns The projected mercator coordinate.
+   * @example
+   * ```ts
+   * let coord = MercatorCoordinate.fromLngLat({ lng: 0, lat: 0}, 0);
+   * coord; // MercatorCoordinate(0.5, 0.5, 0)
+   * ```
+   */
+  static fromLngLat(lngLatLike, altitude = 0) {
+    const lngLat = _lng_lat.LngLat.convert(lngLatLike);
+    return new MercatorCoordinate(mercatorXfromLng(lngLat.lng), mercatorYfromLat(lngLat.lat), mercatorZfromAltitude(altitude, lngLat.lat));
+  }
+
+  /**
+   * Returns the `LngLat` for the coordinate.
+   *
+   * @returns The `LngLat` object.
+   * @example
+   * ```ts
+   * let coord = new MercatorCoordinate(0.5, 0.5, 0);
+   * let lngLat = coord.toLngLat(); // LngLat(0, 0)
+   * ```
+   */
+  toLngLat() {
+    return new _lng_lat.LngLat(lngFromMercatorX(this.x), latFromMercatorY(this.y));
+  }
+
+  /**
+   * Returns the altitude in meters of the coordinate.
+   *
+   * @returns The altitude in meters.
+   * @example
+   * ```ts
+   * let coord = new MercatorCoordinate(0, 0, 0.02);
+   * coord.toAltitude(); // 6914.281956295339
+   * ```
+   */
+  toAltitude() {
+    return altitudeFromMercatorZ(this.z, this.y);
+  }
+
+  /**
+   * 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.
+   */
+  meterInMercatorCoordinateUnits() {
+    // 1 meter / circumference at equator in meters * Mercator projection scale factor at this latitude
+    return 1 / earthCircumfrence * mercatorScale(latFromMercatorY(this.y));
+  }
+}
+exports.MercatorCoordinate = MercatorCoordinate;