@antv/l7-map 2.25.7 → 2.25.9

package/es/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/es/map/geo/mercator_coordinate.js

@@ -0,0 +1,142 @@
+import _defineProperty from "@babel/runtime/helpers/esm/defineProperty";
+import { LngLat, earthRadius } from "./lng_lat";
+/*
+ * The average circumference of the world in meters.
+ */
+const earthCircumfrence = 2 * Math.PI * earthRadius; // meters
+
+/*
+ * The circumference at a line of latitude in meters.
+ */
+function circumferenceAtLatitude(latitude) {
+  return earthCircumfrence * Math.cos(latitude * Math.PI / 180);
+}
+export function mercatorXfromLng(lng) {
+  return (180 + lng) / 360;
+}
+export function mercatorYfromLat(lat) {
+  return (180 - 180 / Math.PI * Math.log(Math.tan(Math.PI / 4 + lat * Math.PI / 360))) / 360;
+}
+export function mercatorZfromAltitude(altitude, lat) {
+  return altitude / circumferenceAtLatitude(lat);
+}
+export function lngFromMercatorX(x) {
+  return x * 360 - 180;
+}
+export function latFromMercatorY(y) {
+  const y2 = 180 - y * 360;
+  return 360 / Math.PI * Math.atan(Math.exp(y2 * Math.PI / 180)) - 90;
+}
+export 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
+ */
+export 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/)
+ */
+export 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) {
+    _defineProperty(this, "x", void 0);
+    _defineProperty(this, "y", void 0);
+    _defineProperty(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 = 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 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));
+  }
+}

package/es/map/geo/transform.d.ts

@@ -0,0 +1,262 @@
+/// <reference types="mapbox__point-geometry" />
+import Point from '@mapbox/point-geometry';
+import { mat2, mat4 } from 'gl-matrix';
+import { EdgeInsets } from './edge_insets';
+import { LngLat } from './lng_lat';
+import { LngLatBounds } from './lng_lat_bounds';
+import { MercatorCoordinate } from './mercator_coordinate';
+import type { PaddingOptions } from './edge_insets';
+export declare const MAX_VALID_LATITUDE = 85.051129;
+/**
+ * @internal
+ * A single transform, generally used for a single tile to be
+ * scaled, rotated, and zoomed.
+ */
+export declare class Transform {
+    tileSize: number;
+    tileZoom: number;
+    lngRange: [number, number];
+    latRange: [number, number];
+    scale: number;
+    width: number;
+    height: number;
+    angle: number;
+    rotationMatrix: mat2;
+    pixelsToGLUnits: [number, number];
+    cameraToCenterDistance: number;
+    mercatorMatrix: mat4;
+    projMatrix: mat4;
+    invProjMatrix: mat4;
+    alignedProjMatrix: mat4;
+    pixelMatrix: mat4;
+    pixelMatrix3D: mat4;
+    pixelMatrixInverse: mat4;
+    glCoordMatrix: mat4;
+    labelPlaneMatrix: mat4;
+    minElevationForCurrentTile: number;
+    _fov: number;
+    _pitch: number;
+    _zoom: number;
+    _unmodified: boolean;
+    _renderWorldCopies: boolean;
+    _minZoom: number;
+    _maxZoom: number;
+    _minPitch: number;
+    _maxPitch: number;
+    _center: LngLat;
+    _elevation: number;
+    _pixelPerMeter: number;
+    _edgeInsets: EdgeInsets;
+    _constraining: boolean;
+    _posMatrixCache: {
+        [_: string]: mat4;
+    };
+    _alignedPosMatrixCache: {
+        [_: string]: mat4;
+    };
+    constructor(minZoom?: number, maxZoom?: number, minPitch?: number, maxPitch?: number, renderWorldCopies?: boolean);
+    clone(): Transform;
+    apply(that: Transform): void;
+    get minZoom(): number;
+    set minZoom(zoom: number);
+    get maxZoom(): number;
+    set maxZoom(zoom: number);
+    get minPitch(): number;
+    set minPitch(pitch: number);
+    get maxPitch(): number;
+    set maxPitch(pitch: number);
+    get renderWorldCopies(): boolean;
+    set renderWorldCopies(renderWorldCopies: boolean | null | undefined);
+    get worldSize(): number;
+    get centerOffset(): Point;
+    get size(): Point;
+    get bearing(): number;
+    set bearing(bearing: number);
+    get pitch(): number;
+    set pitch(pitch: number);
+    get fov(): number;
+    set fov(fov: number);
+    get zoom(): number;
+    set zoom(zoom: number);
+    get center(): LngLat;
+    set center(center: LngLat);
+    /**
+     * Elevation at current center point, meters above sea level
+     */
+    get elevation(): number;
+    set elevation(elevation: number);
+    get padding(): PaddingOptions;
+    set padding(padding: PaddingOptions);
+    /**
+     * The center of the screen in pixels with the top-left corner being (0,0)
+     * and +y axis pointing downwards. This accounts for padding.
+     */
+    get centerPoint(): Point;
+    /**
+     * Returns if the padding params match
+     *
+     * @param padding - the padding to check against
+     * @returns true if they are equal, false otherwise
+     */
+    isPaddingEqual(padding: PaddingOptions): boolean;
+    /**
+     * Helper method to update edge-insets in place
+     *
+     * @param start - the starting padding
+     * @param target - the target padding
+     * @param t - the step/weight
+     */
+    interpolatePadding(start: PaddingOptions, target: PaddingOptions, t: number): void;
+    /**
+     * Return a zoom level that will cover all tiles the transform
+     * @param options - the options
+     * @returns zoom level An integer zoom level at which all tiles will be visible.
+     */
+    coveringZoomLevel(options: {
+        /**
+         * Target zoom level. If true, the value will be rounded to the closest integer. Otherwise the value will be floored.
+         */
+        roundZoom?: boolean;
+        /**
+         * Tile size, expressed in screen pixels.
+         */
+        tileSize: number;
+    }): number;
+    resize(width: number, height: number): void;
+    get unmodified(): boolean;
+    zoomScale(zoom: number): number;
+    scaleZoom(scale: number): number;
+    /**
+     * Convert from LngLat to world coordinates (Mercator coordinates scaled by 512)
+     * @param lnglat - the lngLat
+     * @returns Point
+     */
+    project(lnglat: LngLat): Point;
+    /**
+     * Convert from world coordinates ([0, 512],[0, 512]) to LngLat ([-180, 180], [-90, 90])
+     * @param point - world coordinate
+     * @returns LngLat
+     */
+    unproject(point: Point): LngLat;
+    get point(): Point;
+    /**
+     * get the camera position in LngLat and altitudes in meter
+     * @returns An object with lngLat & altitude.
+     */
+    getCameraPosition(): {
+        lngLat: LngLat;
+        altitude: number;
+    };
+    setLocationAtPoint(lnglat: LngLat, point: Point): void;
+    /**
+     * Given a LngLat location, return the screen point that corresponds to it
+     * @param lnglat - location
+     * @param terrain - optional terrain
+     * @returns screen point
+     */
+    locationPoint(lnglat: LngLat): Point;
+    /**
+     * Given a point on screen, return its lnglat
+     * @param p - screen point
+     * @param terrain - optional terrain
+     * @returns lnglat location
+     */
+    pointLocation(p: Point): LngLat;
+    /**
+     * Given a geographical lnglat, return an unrounded
+     * coordinate that represents it at low zoom level.
+     * @param lnglat - the location
+     * @returns The mercator coordinate
+     */
+    locationCoordinate(lnglat: LngLat): MercatorCoordinate;
+    /**
+     * Given a Coordinate, return its geographical position.
+     * @param coord - mercator coordinates
+     * @returns lng and lat
+     */
+    coordinateLocation(coord: MercatorCoordinate): LngLat;
+    /**
+     * Given a Point, return its mercator coordinate.
+     * @param p - the point
+     * @param terrain - optional terrain
+     * @returns lnglat
+     */
+    pointCoordinate(p: Point): MercatorCoordinate;
+    /**
+     * Given a coordinate, return the screen point that corresponds to it
+     * @param coord - the coordinates
+     * @param elevation - the elevation
+     * @param pixelMatrix - the pixel matrix
+     * @returns screen point
+     */
+    coordinatePoint(coord: MercatorCoordinate, elevation?: number, pixelMatrix?: mat4): Point;
+    /**
+     * Returns the map's geographical bounds. When the bearing or pitch is non-zero, the visible region is not
+     * an axis-aligned rectangle, and the result is the smallest bounds that encompasses the visible region.
+     * @returns Returns a {@link LngLatBounds} object describing the map's geographical bounds.
+     */
+    getBounds(): LngLatBounds;
+    /**
+     * Returns the maximum geographical bounds the map is constrained to, or `null` if none set.
+     * @returns max bounds
+     */
+    getMaxBounds(): LngLatBounds | null;
+    /**
+     * Calculate pixel height of the visible horizon in relation to map-center (e.g. height/2),
+     * multiplied by a static factor to simulate the earth-radius.
+     * The calculated value is the horizontal line from the camera-height to sea-level.
+     * @returns Horizon above center in pixels.
+     */
+    getHorizon(): number;
+    /**
+     * Sets or clears the map's geographical constraints.
+     * @param bounds - A {@link LngLatBounds} object describing the new geographic boundaries of the map.
+     */
+    setMaxBounds(bounds?: LngLatBounds | null): void;
+    customLayerMatrix(): mat4;
+    /**
+     * Get center lngLat and zoom to ensure that
+     * 1) everything beyond the bounds is excluded
+     * 2) a given lngLat is as near the center as possible
+     * Bounds are those set by maxBounds or North & South "Poles" and, if only 1 globe is displayed, antimeridian.
+     */
+    getConstrained(lngLat: LngLat, zoom: number): {
+        center: LngLat;
+        zoom: number;
+    };
+    _constrain(): void;
+    _calcMatrices(): void;
+    maxPitchScaleFactor(): number;
+    /**
+     * The camera looks at the map from a 3D (lng, lat, altitude) location. Let's use `cameraLocation`
+     * as the name for the location under the camera and on the surface of the earth (lng, lat, 0).
+     * `cameraPoint` is the projected position of the `cameraLocation`.
+     *
+     * This point is useful to us because only fill-extrusions that are between `cameraPoint` and
+     * the query point on the surface of the earth can extend and intersect the query.
+     *
+     * When the map is not pitched the `cameraPoint` is equivalent to the center of the map because
+     * the camera is right above the center of the map.
+     */
+    getCameraPoint(): Point;
+    /**
+     * When the map is pitched, some of the 3D features that intersect a query will not intersect
+     * the query at the surface of the earth. Instead the feature may be closer and only intersect
+     * the query because it extrudes into the air.
+     * @param queryGeometry - For point queries, the line from the query point to the "camera point",
+     * for other geometries, the envelope of the query geometry and the "camera point"
+     * @returns a geometry that includes all of the original query as well as all possible ares of the
+     * screen where the *base* of a visible extrusion could be.
+     *
+     */
+    getCameraQueryGeometry(queryGeometry: Array<Point>): Array<Point>;
+    /**
+     * Return the distance to the camera in clip space from a LngLat.
+     * This can be compared to the value from the depth buffer (terrain.depthAtPoint)
+     * to determine whether a point is occluded.
+     * @param lngLat - the point
+     * @param elevation - the point's elevation
+     * @returns depth value in clip space (between 0 and 1)
+     */
+    lngLatToCameraDepth(lngLat: LngLat, elevation: number): number;
+}