@wemap/geo 7.4.0 → 8.0.0-alpha.0

package/dist/wemap-geo.es.js

@@ -349,9 +349,30 @@ class Level {
  */
 class Coordinates {
 
+    /** @type {Number} */
+    _lat;
+
+    /** @type {Number} */
+    _lng;
+
+    /** @type {Number|null} */
+    _alt = null;
+
+    /** @type {Level|null} */
+    _level = null;
+
+    /** @type {[Number, Number, Number]|null} */
+    _ecef;
+
     autoWrap = true;
 
-    constructor(lat, lng, alt, level) {
+    /**
+     * @param {Number} lat
+     * @param {Number} lng
+     * @param {?(Number|null)} alt
+     * @param {?(Level|null)} level
+     */
+    constructor(lat, lng, alt = null, level = null) {
         this.lat = lat;
         this.lng = lng;
         this.alt = alt;
@@ -359,23 +380,28 @@ class Coordinates {
         this._ecef = null;
     }
 
+    /** @type {Number} */
     get lat() {
         return this._lat;
     }
 
+    /** @type {Number} */
     get latitude() {
         return this._lat;
     }
 
+    /** @type {Number} */
     get lng() {
         return this._lng;
     }
 
+    /** @type {Number} */
     get longitude() {
         return this._lng;
     }
 
     /**
+     * @type {Number|null}
      * alt does not denote the altitude of a point but its height from
      *  the "level" field (if defined) or from the ground
      */
@@ -383,10 +409,12 @@ class Coordinates {
         return this._alt;
     }
 
+    /** @type {Level|null} */
     get level() {
         return this._level;
     }
 
+    /** @type {Number} */
     set lat(lat) {
         if (typeof lat === 'number' && Math.abs(lat) <= 90) {
             this._lat = lat;
@@ -396,10 +424,12 @@ class Coordinates {
         this._ecef = null;
     }
 
-    set latitude(lat) {
+    /** @type {Number} */
+    set latitude(_) {
         throw new Error('Please use Coordinate#lat setter instead of Coordinate#latitude');
     }
 
+    /** @type {Number} */
     set lng(lng) {
         if (typeof lng === 'number') {
             this._lng = lng;
@@ -412,10 +442,12 @@ class Coordinates {
         this._ecef = null;
     }
 
-    set longitude(lng) {
+    /** @type {Number} */
+    set longitude(_) {
         throw new Error('Please use Coordinate#lng setter instead of Coordinate#longitude');
     }
 
+    /** @type {Number|null} */
     set alt(alt) {
         if (typeof alt === 'number') {
             this._alt = alt;
@@ -428,6 +460,7 @@ class Coordinates {
         this._ecef = null;
     }
 
+    /** @type {Level|null} */
     set level(level) {
         if (level instanceof Level) {
             this._level = level;
@@ -439,6 +472,10 @@ class Coordinates {
         }
     }
 
+    /**
+     * Deep clone coordinates
+     * @returns {!Coordinates}
+     */
     clone() {
         const output = new Coordinates(this.lat, this.lng, this.alt);
         if (this.level) {
@@ -479,17 +516,35 @@ class Coordinates {
             && Level.equalsTo(pos1.level, pos2.level);
     }
 
+    /**
+     * @param {Coordinates} other
+     * @returns {!Boolean}
+     */
     equalsTo(other) {
         return Coordinates.equalsTo(this, other);
     }
 
+    /**
+     * @param {!Number} distance
+     * @param {!Number} bearing
+     * @param {?Number} elevation
+     * @returns {!Coordinates}
+     * @throws {Error} if elevation is defined and point altitude is not defined
+     */
     destinationPoint(distance, bearing, elevation) {
         const newPoint = this.clone();
         newPoint.move(distance, bearing, elevation);
         return newPoint;
     }
 
-    // Source: http://www.movable-type.co.uk/scripts/latlong.html#destPoint
+    /**
+     * Source: http://www.movable-type.co.uk/scripts/latlong.html#destPoint
+     * @param {!Number} distance
+     * @param {!Number} bearing
+     * @param {?Number} elevation
+     * @returns {!Coordinates}
+     * @throws {Error} if elevation is defined and point altitude is not defined
+     */
     move(distance, bearing, elevation) {
 
         const dR = distance / Constants.R_MAJOR;
@@ -518,7 +573,6 @@ class Coordinates {
             this.alt += elevation;
         }
 
-
         return this;
     }
 
@@ -553,10 +607,19 @@ class Coordinates {
         return Constants.R_MAJOR * cosn;
     }
 
+    /**
+     * @param {!Coordinates} point1
+     * @param {!Coordinates} point2
+     * @returns {!Number}
+     */
     static distanceBetween(point1, point2) {
         return point1.distanceTo(point2);
     }
 
+    /**
+     * @param {!Coordinates} location2
+     * @returns {!Number}
+     */
     bearingTo(location2) {
         const lat1 = deg2rad(this.lat);
         const lat2 = deg2rad(location2.lat);
@@ -566,6 +629,11 @@ class Coordinates {
             Math.cos(lat1) * Math.sin(lat2) - Math.sin(lat1) * Math.cos(lat2) * Math.cos(diffLng));
     }
 
+    /**
+     * @param {!Coordinates} point1
+     * @param {!Coordinates} point2
+     * @returns {!Number}
+     */
     static bearingTo(point1, point2) {
         return point1.bearingTo(point2);
     }
@@ -577,20 +645,25 @@ class Coordinates {
      * as a sphere instead of an ellipse
      */
 
+    /** @type {![Number, Number, Number, Number]} */
     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));
         return Quaternion.multiply(rot1, rot2);
     }
 
+    /** @type {![Number, Number, Number, Number]} */
     get ecefToEnuRotation() {
         const rot1 = Quaternion.fromAxisAngle([1, 0, 0], deg2rad(this.lat) - Math.PI / 2);
         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
+    /**
+     * https://gist.github.com/klucar/1536194
+     * Adapted for spherical formula
+     * @type {![Number, Number, Number]}
+     */
     get ecef() {
 
         if (!this._ecef) {
@@ -608,6 +681,10 @@ class Coordinates {
         return this._ecef;
     }
 
+    /**
+     * @param {![Number, Number, Number]} ecef
+     * @returns {!Coordinates}
+     */
     static fromECEF(ecef) {
 
         const x = ecef[0];
@@ -628,8 +705,13 @@ class Coordinates {
     }
 
 
-    // https://stackoverflow.com/questions/1299567/how-to-calculate-distance-from-a-point-to-a-line-segment-on-a-sphere
-    // Adapted to ECEF
+    /**
+     * https://stackoverflow.com/questions/1299567/how-to-calculate-distance-from-a-point-to-a-line-segment-on-a-sphere
+     * Adapted to ECEF
+     * @param {!Coordinates} p1
+     * @param {!Coordinates} p2
+     * @returns {Coordinates|null}
+     */
     getSegmentProjection(p1, p2) {
 
         const a = Vector3.normalize(p1.ecef);
@@ -669,6 +751,9 @@ class Coordinates {
      * Input / Output
      */
 
+    /**
+     * @returns {!String}
+     */
     toString() {
         let str = '[' + this._lat.toFixed(7) + ', ' + this._lng.toFixed(7);
         if (this._alt !== null) {
@@ -681,6 +766,9 @@ class Coordinates {
         return str;
     }
 
+    /**
+     * @returns {!Object}
+     */
     toJson() {
         const output = {
             lat: this.lat,
@@ -695,10 +783,17 @@ class Coordinates {
         return output;
     }
 
+    /**
+     * @param {!Object} json
+     * @returns {!Coordinates}
+     */
     static fromJson(json) {
         return new Coordinates(json.lat, json.lng, json.alt, Level.fromString(json.level));
     }
 
+    /**
+     * @returns {!Object}
+     */
     toCompressedJson() {
         const output = [this.lat, this.lng];
         if (this.alt !== null || this.level !== null) {
@@ -710,6 +805,10 @@ class Coordinates {
         return output;
     }
 
+    /**
+     * @param {!Object} json
+     * @returns {!Coordinates}
+     */
     static fromCompressedJson(json) {
         const coords = new Coordinates(json[0], json[1]);
         if (json.length > 2) {
@@ -1433,6 +1532,67 @@ class RelativePosition {
  */
 class GeoRelativePosition extends RelativePosition { }
 
+class GeoRef {
+
+    /** @type {!Coordinates} */
+    origin;
+
+    /** @type {number} */
+    scale = 1;
+
+    /** @type {number} */
+    heading = 0;
+
+
+    /**
+     * @param {number[]} localPosition in ENU frame
+     * @returns {Coordinates}
+     */
+    localToWorld(localPosition) {
+        const localPositionScaled = Vector3.multiplyScalar(localPosition, this.scale);
+        const rotationOffset = Quaternion.fromAxisAngle([0, 0, 1], this.heading);
+        const ecefToEnuRotationOrigin = Quaternion.multiply(rotationOffset, this.origin.ecefToEnuRotation);
+        const ecefTranslation = Quaternion.rotate(ecefToEnuRotationOrigin, localPositionScaled);
+        const ecef = Vector3.add(this.origin.ecef, ecefTranslation);
+        return Coordinates.fromECEF(ecef);
+    }
+
+    /**
+     * @param {Coordinates} coords
+     * @returns {number[]} localPosition in ENU frame
+     */
+    worldToLocal(coords) {
+        const rotationOffset = Quaternion.fromAxisAngle([0, 0, 1], -this.heading);
+        const enuToEcefRotationOrigin = Quaternion.multiply(this.origin.enuToEcefRotation, rotationOffset);
+        const ecefTranslation = Vector3.subtract(coords.ecef, this.origin.ecef);
+        const ecefTranslationScaled = Vector3.multiplyScalar(ecefTranslation, 1 / this.scale);
+        return Quaternion.rotate(enuToEcefRotationOrigin, ecefTranslationScaled);
+    }
+
+    /**
+     * @returns {Object}
+     */
+    toJson() {
+        return {
+            origin: this.origin.toJson(),
+            scale: this.scale,
+            heading: this.heading
+        };
+    }
+
+    /**
+     * @param {Object} json
+     * @returns {GeoRef}
+     */
+    static fromJson(json) {
+        const geoRef = new GeoRef();
+        geoRef.origin = Coordinates.fromJson(json.origin);
+        geoRef.scale = json.scale;
+        geoRef.heading = json.heading;
+        return geoRef;
+    }
+}
+
 class Attitude {
 
     _quaternion = [1, 0, 0, 0];
@@ -2468,11 +2628,11 @@ class MapMatching {
             checkEdge = false;
         }
 
-        if (!Level.equalsTo(location.level, edge.node1.coords.level) && !edge.node1.io) {
+        if (!Level.equalsTo(location.level, edge.node1.coords.level) && !(edge.node1.io && !location.level)) {
             checkNode1 = false;
         }
 
-        if (!Level.equalsTo(location.level, edge.node2.coords.level) && !edge.node2.io) {
+        if (!Level.equalsTo(location.level, edge.node2.coords.level) && !(edge.node2.io && !location.level)) {
             checkNode2 = false;
         }
 
@@ -2776,6 +2936,10 @@ class GraphRouter {
 
         const createdNodes = [];
 
+        /**
+         * @param {GraphNode|Coordinates} point
+         * @returns {GraphNode}
+         */
         const retrieveOrCreateNearestNode = point => {
             if (point instanceof GraphNode) {
                 return point;
@@ -2788,10 +2952,13 @@ class GraphRouter {
 
             const proj = this._mapMatching.getProjection(point, true, false, false, acceptEdgeFn);
             if (!proj) {
-                throw new NoRouteFoundError(start, end,
-                    `Point ${point.toString()} is too far from the network `
-                    + `> ${this._mapMatching.maxDistance.toFixed(0)} meters`
-                );
+                let message = `Point ${point.toString()} is too far from the network `
+                    + `> ${this._mapMatching.maxDistance.toFixed(0)} meters.`;
+                if (point.level) {
+                    message += ' If it is a multi-level map, please verify if you have'
+                        + ` a network at level ${point.level.toString()}.`;
+                }
+                throw new NoRouteFoundError(start, end, message);
             }
             if (proj.nearestElement instanceof GraphNode) {
                 return proj.nearestElement;
@@ -2999,5 +3166,5 @@ class GraphRouter {
     }
 }
 
-export { AbsoluteHeading, Attitude, BoundingBox, Constants, Coordinates, GeoRelativePosition, GraphEdge, GraphItinerary, GraphNode, GraphProjection, GraphRouter, GraphRouterOptions, GraphUtils, Level, MapMatching, Network, NoRouteFoundError, RelativePosition, UserPosition, Utils };
+export { AbsoluteHeading, Attitude, BoundingBox, Constants, Coordinates, GeoRef, GeoRelativePosition, GraphEdge, GraphItinerary, GraphNode, GraphProjection, GraphRouter, GraphRouterOptions, GraphUtils, Level, MapMatching, Network, NoRouteFoundError, RelativePosition, UserPosition, Utils };
 //# sourceMappingURL=wemap-geo.es.js.map