@wemap/geo 11.5.0 → 11.7.0

package/dist/index.mjs

@@ -22,21 +22,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;
@@ -55,6 +55,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);
@@ -73,6 +76,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;
@@ -101,6 +107,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);
@@ -123,6 +134,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);
@@ -156,6 +170,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);
@@ -166,6 +186,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);
@@ -199,6 +222,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);
@@ -265,8 +294,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");
@@ -314,6 +343,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;
   }
@@ -328,6 +361,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) {
@@ -352,11 +388,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);
@@ -380,6 +423,9 @@ class Coordinates {
     }
     return this;
   }
+  /**
+   * Returns a distance between two points in meters
+   */
   distanceTo(location2) {
     const lat1 = this.lat;
     const lng1 = this.lng;
@@ -414,6 +460,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 = Quaternion.fromAxisAngle([0, 0, 1], Math.PI / 2 + deg2rad(this.lng));
     const rot2 = Quaternion.fromAxisAngle([1, 0, 0], Math.PI / 2 - deg2rad(this.lat));
@@ -424,6 +475,10 @@ class Coordinates {
     const rot2 = Quaternion.fromAxisAngle([0, 0, 1], -deg2rad(this.lng) - Math.PI / 2);
     return Quaternion.multiply(rot1, rot2);
   }
+  /**
+   * https://gist.github.com/klucar/1536194
+   * Adapted for spherical formula
+   */
   get ecef() {
     if (!this._ecef) {
       const lat = deg2rad(this.lat);
@@ -449,6 +504,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 = Vector3.normalize(p1.ecef);
     const b = Vector3.normalize(p2.ecef);
@@ -476,6 +535,9 @@ class Coordinates {
     }
     return projection;
   }
+  /**
+   * Input / Output
+   */
   toString() {
     let str = "[" + this._lat.toFixed(7) + ", " + this._lng.toFixed(7);
     if (this._alt !== null) {
@@ -567,6 +629,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,
@@ -738,11 +802,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) {
@@ -754,14 +818,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;
@@ -784,6 +857,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");
@@ -792,6 +869,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;
@@ -801,27 +883,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;
   }
@@ -831,6 +937,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]),
@@ -846,6 +955,9 @@ class BoundingBox {
       new BoundingBox(coords[0], coords[0])
     );
   }
+  /**
+   * Returns the WSEN array
+   */
   toArray() {
     return [this.getWest(), this.getSouth(), this.getEast(), this.getNorth()];
   }
@@ -883,6 +995,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;
@@ -918,6 +1036,9 @@ class GeoRef {
     __publicField(this, "heading", 0);
     this.origin = origin;
   }
+  /**
+   * LocalPosition in ENU frame
+   */
   localToWorld(localPosition) {
     const enuTranslationScaled = Vector3.multiplyScalar(localPosition, this.scale);
     const rotationOffset = Quaternion.fromAxisAngle([0, 0, 1], this.heading);
@@ -926,6 +1047,9 @@ class GeoRef {
     const ecef = Vector3.sum(this.origin.ecef, ecefTranslation);
     return Coordinates.fromECEF(ecef);
   }
+  /**
+   * LocalPosition in ENU frame
+   */
   worldToLocal(coords) {
     const rotationOffset = Quaternion.fromAxisAngle([0, 0, 1], -this.heading);
     const ecefToEnuRotationOrigin = Quaternion.multiply(this.origin.ecefToEnuRotation, rotationOffset);
@@ -1043,6 +1167,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 = Quaternion.multiply(
       Quaternion.inverse(attitudeStart.quaternion),
@@ -1084,6 +1211,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;
@@ -1141,12 +1273,18 @@ class GeoGraphEdge extends 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();
@@ -1175,6 +1313,9 @@ class GeoGraphVertex extends GraphVertex {
   bearingTo(other) {
     return this.coords.bearingTo(other.coords);
   }
+  /**
+   * Does not include "edges" property
+   */
   toJson() {
     return this.coords.toCompressedJson();
   }
@@ -1198,6 +1339,9 @@ class GeoGraphVertex extends GraphVertex {
     }
     this.coords.level = tmpLevel;
   }
+  /**
+   * We suppose inferVertexLevelFromEdges() was called before
+   */
   inferVertexLevelByNeighboors() {
     const { level } = this.coords;
     if (level === null || !Level.isRange(level)) {
@@ -1214,6 +1358,9 @@ class GeoGraphVertex extends GraphVertex {
     }
     return true;
   }
+  /**
+   * We suppose inferVertexLevelFromEdges() and inferVertexLevelByNeighboors() were called before
+   */
   inferVertexLevelByRecursion() {
     const { level } = this.coords;
     if (level === null || !Level.isRange(level)) {
@@ -1278,13 +1425,21 @@ class GeoGraph extends 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];
@@ -1302,8 +1457,9 @@ class GeoGraph extends 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;
     });
@@ -1338,6 +1494,10 @@ class GeoGraph extends 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)
@@ -1365,7 +1525,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);
@@ -1384,6 +1544,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];
@@ -1415,11 +1581,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");
@@ -1492,10 +1668,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);
@@ -1557,7 +1733,7 @@ class NoRouteFoundError extends Error {
     return message;
   }
 }
-const _GeoGraphRouter = class {
+const _GeoGraphRouter = class _GeoGraphRouter {
   constructor(graph) {
     __publicField(this, "_mapMatching");
     __publicField(this, "_graph");
@@ -1716,11 +1892,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;
 export {
   AbsoluteHeading,
   Attitude,