@wemap/geo 11.5.0 → 11.7.0

package/dist/index.js

@@ -5,12 +5,10 @@ var __publicField = (obj, key, value) => {
   __defNormalProp(obj, typeof key !== "symbol" ? key + "" : key, value);
   return value;
 };
-Object.defineProperties(exports, { __esModule: { value: true }, [Symbol.toStringTag]: { value: "Module" } });
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
 const maths = require("@wemap/maths");
 const utils = require("@wemap/utils");
 const Logger = require("@wemap/logger");
-const _interopDefaultLegacy = (e) => e && typeof e === "object" && "default" in e ? e : { default: e };
-const Logger__default = /* @__PURE__ */ _interopDefaultLegacy(Logger);
 const R_MAJOR = 6378137;
 const R_MINOR = 63567523142e-4;
 const EARTH_GRAVITY = 9.80665;
@@ -26,21 +24,21 @@ const R_MINOR_4 = R_MINOR_2 * R_MINOR_2;
 const CIRCUMFERENCE = R_MAJOR * 2 * Math.PI;
 const Constants = /* @__PURE__ */ Object.freeze(/* @__PURE__ */ Object.defineProperty({
   __proto__: null,
-  R_MAJOR,
-  R_MINOR,
+  CIRCUMFERENCE,
   EARTH_GRAVITY,
-  EPS_DEG_MM,
-  EPS_MM,
-  ELLIPSOID_FLATNESS,
   ECCENTRICITY,
   ECCENTRICITY_2,
+  ELLIPSOID_FLATNESS,
+  EPS_DEG_MM,
+  EPS_MM,
+  R_MAJOR,
   R_MAJOR_2,
   R_MAJOR_4,
+  R_MINOR,
   R_MINOR_2,
-  R_MINOR_4,
-  CIRCUMFERENCE
+  R_MINOR_4
 }, Symbol.toStringTag, { value: "Module" }));
-const _Level = class {
+const _Level = class _Level {
   static checkType(level) {
     if (level === null) {
       return;
@@ -59,6 +57,9 @@ const _Level = class {
     }
     throw Error(`Unknown level format: ${level}`);
   }
+  /**
+   * Return true if the level is a range, false otherwise
+   */
   static isRange(level) {
     if (_Level.VERIFY_TYPING) {
       this.checkType(level);
@@ -77,6 +78,9 @@ const _Level = class {
     }
     return [level[0], level[1]];
   }
+  /**
+   * Create a level from a string (eg. 1, -2, 1;2, -2;3, 2;-1, 0.5;1 ...)
+   */
   static fromString(str) {
     if (str === null) {
       return null;
@@ -105,6 +109,11 @@ const _Level = class {
     }
     throw Error(`Cannot parse following level: ${str}`);
   }
+  /**
+   * Returns if a level is contained in another
+   * @param {null|number|[number, number]} container The container level
+   * @param {null|number|[number, number]} targeted The targeted level
+   */
   static contains(container, targeted) {
     if (_Level.VERIFY_TYPING) {
       this.checkType(container);
@@ -127,6 +136,9 @@ const _Level = class {
     }
     return container <= targeted[0] && container >= targeted[1];
   }
+  /**
+   * Retrieve the intersection of two levels
+   */
   static intersection(first, second) {
     if (_Level.VERIFY_TYPING) {
       this.checkType(first);
@@ -160,6 +172,12 @@ const _Level = class {
     }
     return up < low ? null : [low, up];
   }
+  /**
+  * Retrieve the intersection of two levels
+  * @param {null|number|[number, number]} first The first level
+  * @param {null|number|[number, number]} second The second level
+  * @returns {boolean}
+  */
   static intersect(first, second) {
     if (_Level.VERIFY_TYPING) {
       this.checkType(first);
@@ -170,6 +188,9 @@ const _Level = class {
     }
     return this.intersection(first, second) !== null;
   }
+  /**
+   * Retrieve the union of two levels
+   */
   static union(first, second) {
     if (_Level.VERIFY_TYPING) {
       this.checkType(first);
@@ -203,6 +224,12 @@ const _Level = class {
     }
     return [low, up];
   }
+  /**
+   * Multiply a level by a factor
+   * @param {null|number|[number, number]} level the level to multiply
+   * @param {number} factor
+   * @returns {null|number|[number, number]}
+   */
   static multiplyBy(level, factor) {
     if (_Level.VERIFY_TYPING) {
       this.checkType(level);
@@ -269,8 +296,8 @@ const _Level = class {
     return null;
   }
 };
+__publicField(_Level, "VERIFY_TYPING", false);
 let Level = _Level;
-__publicField(Level, "VERIFY_TYPING", false);
 class Coordinates {
   constructor(lat, lng, alt = null, level = null) {
     __publicField(this, "_lat");
@@ -318,6 +345,10 @@ class Coordinates {
   set longitude(_) {
     throw new Error("Please use Coordinates#lng setter instead of Coordinate#longitude");
   }
+  /**
+   * alt does not denote the altitude of a point but its height from
+   *  the "level" field (if defined) or from the ground
+   */
   get alt() {
     return this._alt;
   }
@@ -332,6 +363,9 @@ class Coordinates {
     Level.checkType(level);
     this._level = level;
   }
+  /**
+   * Deep clone coordinates
+   */
   clone() {
     const output = new Coordinates(this.lat, this.lng, this.alt);
     if (this.level !== null) {
@@ -356,11 +390,18 @@ class Coordinates {
   equals(other) {
     return Coordinates.equals(this, other);
   }
+  /**
+   * @throws {Error} if elevation is defined and point altitude is not defined
+   */
   destinationPoint(distance, bearing, elevation = null) {
     const newPoint = this.clone();
     newPoint.move(distance, bearing, elevation);
     return newPoint;
   }
+  /**
+   * Source: http://www.movable-type.co.uk/scripts/latlong.html#destPoint
+   * @throws {Error} if elevation is defined and point altitude is not defined
+   */
   move(distance, bearing, elevation = null) {
     const dR = distance / R_MAJOR;
     const cosDr = Math.cos(dR);
@@ -384,6 +425,9 @@ class Coordinates {
     }
     return this;
   }
+  /**
+   * Returns a distance between two points in meters
+   */
   distanceTo(location2) {
     const lat1 = this.lat;
     const lng1 = this.lng;
@@ -418,6 +462,11 @@ class Coordinates {
   static bearingTo(point1, point2) {
     return point1.bearingTo(point2);
   }
+  /**
+   * ECEF Transformations
+   * Here we used a light version of ECEF considering earth
+   * as a sphere instead of an ellipse
+   */
   get enuToEcefRotation() {
     const rot1 = maths.Quaternion.fromAxisAngle([0, 0, 1], Math.PI / 2 + maths.deg2rad(this.lng));
     const rot2 = maths.Quaternion.fromAxisAngle([1, 0, 0], Math.PI / 2 - maths.deg2rad(this.lat));
@@ -428,6 +477,10 @@ class Coordinates {
     const rot2 = maths.Quaternion.fromAxisAngle([0, 0, 1], -maths.deg2rad(this.lng) - Math.PI / 2);
     return maths.Quaternion.multiply(rot1, rot2);
   }
+  /**
+   * https://gist.github.com/klucar/1536194
+   * Adapted for spherical formula
+   */
   get ecef() {
     if (!this._ecef) {
       const lat = maths.deg2rad(this.lat);
@@ -453,6 +506,10 @@ class Coordinates {
     newPoint._ecef = ecef;
     return newPoint;
   }
+  /**
+   * https://stackoverflow.com/questions/1299567/how-to-calculate-distance-from-a-point-to-a-line-segment-on-a-sphere
+   * Adapted to ECEF
+   */
   getSegmentProjection(p1, p2) {
     const a = maths.Vector3.normalize(p1.ecef);
     const b = maths.Vector3.normalize(p2.ecef);
@@ -480,6 +537,9 @@ class Coordinates {
     }
     return projection;
   }
+  /**
+   * Input / Output
+   */
   toString() {
     let str = "[" + this._lat.toFixed(7) + ", " + this._lng.toFixed(7);
     if (this._alt !== null) {
@@ -571,6 +631,8 @@ class UserPosition extends Coordinates {
     newPoint.move(distance, bearing, elevation);
     return newPoint;
   }
+  // Create a UserPosition with lat, lng, alt from Coordinates coordinates and
+  //   other fields from another UserPosition
   static fromCoordinates(coordinates) {
     return new UserPosition(
       coordinates.lat,
@@ -742,11 +804,11 @@ function calcDistance(coords) {
 }
 const Utils = /* @__PURE__ */ Object.freeze(/* @__PURE__ */ Object.defineProperty({
   __proto__: null,
+  calcDistance,
+  geolocationPositionToUserPosition,
   sampleRoute,
-  trimRoute,
   simplifyRoute,
-  geolocationPositionToUserPosition,
-  calcDistance
+  trimRoute
 }, Symbol.toStringTag, { value: "Module" }));
 class BoundingBox {
   constructor(northEast, southWest) {
@@ -758,14 +820,23 @@ class BoundingBox {
       throw new Error("Incorrect bounding box");
     }
   }
+  /**
+   * Returns the geographical coordinate equidistant from the bounding box's corners.
+   */
   get center() {
     const latCenter = (this.southWest.lat + this.northEast.lat) / 2;
     const lngCenter = (this.northEast.lng + this.southWest.lng) / 2;
     return new Coordinates(latCenter, lngCenter);
   }
+  /**
+   * Check if a point is contained in the bounding box.
+   */
   contains(point) {
     return point.lat <= this.northEast.lat && point.lat >= this.southWest.lat && point.lng <= this.northEast.lng && point.lng >= this.southWest.lng;
   }
+  /**
+   * Extend the bounds to include a given LngLat or LngLatBounds.
+   */
   extend(obj) {
     const sw = this.southWest, ne = this.northEast;
     let sw2, ne2;
@@ -788,6 +859,10 @@ class BoundingBox {
     );
     return this;
   }
+  /**
+   * This method extends the bounding box with a value in meters
+   * /*\ This method is not precise as distance differs in function of latitude
+   */
   extendsWithMeasure(measure) {
     if (typeof measure !== "number") {
       throw new Error("measure is not a number");
@@ -796,6 +871,11 @@ class BoundingBox {
     this.southWest = this.southWest.clone().destinationPoint(measure, -Math.PI / 2).destinationPoint(measure, Math.PI);
     return this;
   }
+  /**
+   * Returns bounds created by extending or retracting the current bounds by a given ratio in each direction.
+   * For example, a ratio of 0.5 extends the bounds by 50% in each direction.
+   * Negative values will retract the bounds.
+   */
   pad(bufferRatio) {
     const sw = this.southWest;
     const ne = this.northEast;
@@ -805,27 +885,51 @@ class BoundingBox {
     this.northEast = new Coordinates(ne.lat + heightBuffer, ne.lng + widthBuffer);
     return this;
   }
+  /**
+   * Returns the southwest corner of the bounding box.
+   */
   getSouthWest() {
     return this.southWest;
   }
+  /**
+  * Returns the northeast corner of the bounding box.
+  */
   getNorthEast() {
     return this.northEast;
   }
+  /**
+  * Returns the northwest corner of the bounding box.
+  */
   getNorthWest() {
     return new Coordinates(this.getNorth(), this.getWest());
   }
+  /**
+  * Returns the southeast corner of the bounding box.
+  */
   getSouthEast() {
     return new Coordinates(this.getSouth(), this.getEast());
   }
+  /**
+  * Returns the west edge of the bounding box.
+  */
   getWest() {
     return this.southWest.lng;
   }
+  /**
+  * Returns the south edge of the bounding box.
+  */
   getSouth() {
     return this.southWest.lat;
   }
+  /**
+  * Returns the east edge of the bounding box.
+  */
   getEast() {
     return this.northEast.lng;
   }
+  /**
+  * Returns the north edge of the bounding box.
+  */
   getNorth() {
     return this.northEast.lat;
   }
@@ -835,6 +939,9 @@ class BoundingBox {
   equals(other) {
     return BoundingBox.equals(this, other);
   }
+  /**
+   * Create a BoundingBox from a WSEN array
+   */
   static fromArray(bounds) {
     return new BoundingBox(
       new Coordinates(bounds[3], bounds[2]),
@@ -850,6 +957,9 @@ class BoundingBox {
       new BoundingBox(coords[0], coords[0])
     );
   }
+  /**
+   * Returns the WSEN array
+   */
   toArray() {
     return [this.getWest(), this.getSouth(), this.getEast(), this.getNorth()];
   }
@@ -887,6 +997,12 @@ class RelativePosition {
   clone() {
     return new RelativePosition(this.x, this.y, this.z, this.time, this.accuracy, this.bearing);
   }
+  /**
+   * Compares two RelativePosition
+   * @param {RelativePosition} pos1 position 1
+   * @param {RelativePosition} pos2 position 2
+   * @param {Number} eps x, y, z epsilon in meters (default: 1e-3 [= 1mm])
+   */
   static equals(pos1, pos2, eps = EPS_MM) {
     if (pos1 === null && pos1 === pos2) {
       return true;
@@ -922,6 +1038,9 @@ class GeoRef {
     __publicField(this, "heading", 0);
     this.origin = origin;
   }
+  /**
+   * LocalPosition in ENU frame
+   */
   localToWorld(localPosition) {
     const enuTranslationScaled = maths.Vector3.multiplyScalar(localPosition, this.scale);
     const rotationOffset = maths.Quaternion.fromAxisAngle([0, 0, 1], this.heading);
@@ -930,6 +1049,9 @@ class GeoRef {
     const ecef = maths.Vector3.sum(this.origin.ecef, ecefTranslation);
     return Coordinates.fromECEF(ecef);
   }
+  /**
+   * LocalPosition in ENU frame
+   */
   worldToLocal(coords) {
     const rotationOffset = maths.Quaternion.fromAxisAngle([0, 0, 1], -this.heading);
     const ecefToEnuRotationOrigin = maths.Quaternion.multiply(this.origin.ecefToEnuRotation, rotationOffset);
@@ -1047,6 +1169,9 @@ class Attitude {
   clone() {
     return new Attitude(this.quaternion.slice(0), this.time, this.accuracy);
   }
+  /**
+   * Calculate the relative attitude between two given attitudes
+   */
   static diff(attitudeStart, attitudeEnd) {
     const quaternionDiff = maths.Quaternion.multiply(
       maths.Quaternion.inverse(attitudeStart.quaternion),
@@ -1088,6 +1213,11 @@ class AbsoluteHeading {
       this.accuracy
     );
   }
+  /**
+   * Compares two AbsoluteHeading
+   * @param {AbsoluteHeading} heading1 heading 1
+   * @param {AbsoluteHeading} heading2 heading 2
+   */
   static equals(heading1, heading2) {
     if (heading1 === null && heading1 === heading2) {
       return true;
@@ -1145,12 +1275,18 @@ class GeoGraphEdge extends utils.GraphEdge {
     Level.checkType(level);
     this._level = level;
   }
+  /**
+   * Get edge bearing from vertex1 to vertex2
+   */
   get bearing() {
     if (!this._computedSizeAndBearing) {
       this._computeSizeAndBearing();
     }
     return this._bearing;
   }
+  /**
+   * get edge length
+   */
   get length() {
     if (!this._computedSizeAndBearing) {
       this._computeSizeAndBearing();
@@ -1179,6 +1315,9 @@ class GeoGraphVertex extends utils.GraphVertex {
   bearingTo(other) {
     return this.coords.bearingTo(other.coords);
   }
+  /**
+   * Does not include "edges" property
+   */
   toJson() {
     return this.coords.toCompressedJson();
   }
@@ -1202,6 +1341,9 @@ class GeoGraphVertex extends utils.GraphVertex {
     }
     this.coords.level = tmpLevel;
   }
+  /**
+   * We suppose inferVertexLevelFromEdges() was called before
+   */
   inferVertexLevelByNeighboors() {
     const { level } = this.coords;
     if (level === null || !Level.isRange(level)) {
@@ -1218,6 +1360,9 @@ class GeoGraphVertex extends utils.GraphVertex {
     }
     return true;
   }
+  /**
+   * We suppose inferVertexLevelFromEdges() and inferVertexLevelByNeighboors() were called before
+   */
   inferVertexLevelByRecursion() {
     const { level } = this.coords;
     if (level === null || !Level.isRange(level)) {
@@ -1282,13 +1427,21 @@ class GeoGraph extends utils.Graph {
     return boundingBox;
   }
   toCompressedJson() {
+    const createEdgeExtras = (edge) => {
+      const extras = {};
+      if (edge.isOneway) {
+        extras.oneway = true;
+      }
+      return extras;
+    };
     return {
       vertices: this.vertices.map((vertex) => vertex.toJson()),
       edges: this.edges.map((edge) => {
         const vertex1Idx = this.vertices.indexOf(edge.vertex1);
         const vertex2Idx = this.vertices.indexOf(edge.vertex2);
-        if (edge.isOneway) {
-          return [vertex1Idx, vertex2Idx, edge.level, true];
+        const edgeExtras = createEdgeExtras(edge);
+        if (Object.keys(edgeExtras).length > 0) {
+          return [vertex1Idx, vertex2Idx, edge.level, edgeExtras];
         }
         if (edge.level !== null) {
           return [vertex1Idx, vertex2Idx, edge.level];
@@ -1306,8 +1459,9 @@ class GeoGraph extends utils.Graph {
         geograph.vertices[jsonEdge[1]],
         { level: jsonEdge.length > 2 ? jsonEdge[2] : null }
       );
-      if (jsonEdge.length > 3 && jsonEdge[3]) {
-        edge.isOneway = true;
+      const extras = jsonEdge.length > 3 ? jsonEdge[3] : {};
+      if (typeof extras.oneway !== "undefined") {
+        edge.isOneway = extras.oneway;
       }
       return edge;
     });
@@ -1342,6 +1496,10 @@ class GeoGraph extends utils.Graph {
     }
     return geograph;
   }
+  /**
+   * Create edges From MultiLevel Itinerary for a given level
+   * @param useMultiLevelEdges use segments which intersect both levels (stairs, elevators...)
+   */
   getEdgesAtLevel(targetLevel, useMultiLevelEdges = true) {
     return this.edges.filter(
       ({ level }) => useMultiLevelEdges ? Level.intersect(targetLevel, level) : Level.contains(targetLevel, level)
@@ -1369,7 +1527,7 @@ class GeoGraphProjection {
     this.nearestElement = nearestElement;
   }
 }
-const _GeoGraphProjectionHandler = class {
+const _GeoGraphProjectionHandler = class _GeoGraphProjectionHandler {
   constructor(graph = null) {
     __publicField(this, "graph", null);
     __publicField(this, "_maxDistance", Number.MAX_VALUE);
@@ -1388,6 +1546,12 @@ const _GeoGraphProjectionHandler = class {
   get maxDistance() {
     return this._maxDistance;
   }
+  /**
+   * Check if the specified edge and its vertices can be used for projection
+   * @returns an array of two elements.
+   *  First is true if projection will be used on the specified edge, false otherwise.
+   *  Second is true if projection will be used on the vertices of the specified edge, false otherwise.
+   */
   _shouldProjectOnEdgeAndVertices(edge, location, useBearing, useMultiLevelSegments, acceptEdgeFn) {
     if (!acceptEdgeFn(edge)) {
       return [false, false, false];
@@ -1419,11 +1583,21 @@ const _GeoGraphProjectionHandler = class {
     toCoordinates.lng = fromCoordinates.lng;
     toCoordinates.level = Level.clone(fromCoordinates.level);
   }
+  /**
+   * IO Vertices are typical because they have a non-null level but projection car works on them.
+   * This function handles the case where the projection is on an IO vertex and a location with
+   * a null level is required.
+   */
   static _handleLevelsWithIOVertices(projection, location, projectionVertex) {
     if (location.level === null && projectionVertex.io) {
       projection.level = null;
     }
   }
+  /**
+   * Main function for map-matching, the networks have to be set before calling this function
+   * The function will returns a GraphProjection object given a coordinates object and a set
+   * of options (useDistance, useBearing, useMultiLevelSegments, acceptEdgeFn).
+   */
   getProjection(location, useDistance = false, useBearing = false, useMultiLevelSegments = true, acceptEdgeFn = () => true) {
     if (this.graph === null) {
       throw new Error("Graph has not been set yet");
@@ -1496,10 +1670,10 @@ const _GeoGraphProjectionHandler = class {
     );
   }
 };
-let GeoGraphProjectionHandler = _GeoGraphProjectionHandler;
-__publicField(GeoGraphProjectionHandler, "_updateProjectionLevelFromEdge", (_edge, _projection) => {
+__publicField(_GeoGraphProjectionHandler, "_updateProjectionLevelFromEdge", (_edge, _projection) => {
   _projection.level = Level.clone(_edge.level);
 });
+let GeoGraphProjectionHandler = _GeoGraphProjectionHandler;
 class GeoGraphItinerary extends GeoGraph {
   constructor(start, end, vertices, edges, edgesWeights) {
     super(vertices, edges);
@@ -1522,7 +1696,7 @@ class GeoGraphItinerary extends GeoGraph {
       const prevVertex = arr[idx - 1];
       const edge = GeoGraphEdge.getEdgeByVertices(prevVertex.edges, prevVertex, vertex);
       if (!edge) {
-        Logger__default.default.error("Cannot retrieve edge to create itinerary");
+        Logger.error("Cannot retrieve edge to create itinerary");
         return;
       }
       edges.push(new GeoGraphEdge(
@@ -1561,7 +1735,7 @@ class NoRouteFoundError extends Error {
     return message;
   }
 }
-const _GeoGraphRouter = class {
+const _GeoGraphRouter = class _GeoGraphRouter {
   constructor(graph) {
     __publicField(this, "_mapMatching");
     __publicField(this, "_graph");
@@ -1720,11 +1894,11 @@ const _GeoGraphRouter = class {
     return GeoGraphItinerary.fromGraphVertices(start.coords, end.coords, path, edgesWeights);
   }
 };
-let GeoGraphRouter = _GeoGraphRouter;
-__publicField(GeoGraphRouter, "DEFAULT_OPTIONS", {
+__publicField(_GeoGraphRouter, "DEFAULT_OPTIONS", {
   projectionMaxDistance: 50,
   weightEdgeFn: (edge) => edge.length
 });
+let GeoGraphRouter = _GeoGraphRouter;
 exports.AbsoluteHeading = AbsoluteHeading;
 exports.Attitude = Attitude;
 exports.BoundingBox = BoundingBox;