@wemap/geo 9.0.0 → 9.0.2

package/dist/wemap-geo.es.js

@@ -31,309 +31,351 @@ Constants.CIRCUMFERENCE = Constants.R_MAJOR * 2 * Math.PI;
 
 /**
  * A Level is the representation of a building floor number
- * A level can be a simple number (val) or a range (low, up)
- * To know if a level is a range or a number, isRange can be used
+ * A level can be a simple number or a range (low, up)
+ * The range is an array of two numbers
  */
 class Level {
 
-    /** @type {number?} */
-    val = null;
-
     /** @type {boolean} */
-    isRange = false;
-
-    /** @type {number?} */
-    low = null;
-
-    /** @type {number?} */
-    up = null;
+    VERIFY_TYPING = false;
 
     /**
-     * Level constructor
-     *  1 argument: level is not a range and first argument is the level
-     *  2 arguments: level is a range
-     * @param {number} arg1 if arg2: low value, otherwise: level
-     * @param {number} arg2 (optional) up value
+     * @param {null|number|[number, number]} level
+     * @throws {Error}
      */
-    constructor(arg1, arg2) {
-        if (typeof arg1 !== 'number' || isNaN(arg1)) {
-            throw new Error('first argument is mandatory');
+    static checkType(level) {
+        if (level === null) {
+            return;
         }
-        if (typeof arg2 === 'number' && !isNaN(arg2)) {
-            if (arg1 === arg2) {
-                this.isRange = false;
-                this.val = arg1;
-            } else {
-                this.isRange = true;
-                this.low = Math.min(arg1, arg2);
-                this.up = Math.max(arg1, arg2);
+        if (typeof level === 'number' && !isNaN(level)) {
+            return;
+        }
+        if (Array.isArray(level) && level.length === 2) {
+            const [low, up] = level;
+            if (typeof low === 'number' && !isNaN(low)
+                && typeof up === 'number' && !isNaN(up)) {
+                if (low > up || low === up) {
+                    throw Error(`Invalid level range: [${low}, ${up}]`);
+                }
+                return;
             }
-        } else if (typeof arg2 === 'undefined') {
-            this.isRange = false;
-            this.val = arg1;
-        } else {
-            throw new Error('second argument is not a number');
         }
+        throw Error(`Unknown level format: ${level}`);
     }
 
-    clone() {
-        if (this.isRange) {
-            return new Level(this.low, this.up);
+    /**
+     * Return true if the level is a range, false otherwise
+     * @param {null|number|[number, number]} level
+     * @returns {boolean}
+     */
+    static isRange(level) {
+        if (this.VERIFY_TYPING) {
+            this.checkType(level);
         }
-        return new Level(this.val);
+        return Array.isArray(level);
+    }
+
+    /**
+     * @param {null|number|[number, number]} level
+     * @returns {null|number|[number, number]}
+     * @throws {Error}
+     */
+    static clone(level) {
+        if (this.VERIFY_TYPING) {
+            this.checkType(level);
+        }
+        if (level === null) {
+            return null;
+        }
+        if (typeof level === 'number') {
+            return level;
+        }
+
+        return [level[0], level[1]];
     }
 
     /**
      * Create a level from a string
      * @param {string} str level in str format (eg. 1, -2, 1;2, -2;3, 2;-1, 0.5;1 ...)
+     * @returns {null|number|[number, number]}
+     * @throws {Error}
      */
     static fromString(str) {
 
-        if (typeof str !== 'string') {
+        if (str === null) {
             return null;
         }
 
+        if (typeof str !== 'string') {
+            throw Error(`argument must be a string, got ${typeof str}`);
+        }
+
         if (!isNaN(Number(str))) {
-            return new Level(parseFloat(str));
+            return parseFloat(str);
         }
 
         const splited = str.split(';');
         if (splited.length === 2) {
-            if (!isNaN(Number(splited[0])) && !isNaN(Number(splited[1]))) {
-                return new Level(parseFloat(splited[0]), parseFloat(splited[1]));
-            }
+            const low = Number(splited[0]);
+            const up = Number(splited[1]);
+            this.checkType([low, up]);
+            return [parseFloat(splited[0]), parseFloat(splited[1])];
         }
 
-        Logger.warn('Cannot parse following level: ' + str);
-        return null;
-    }
-
-    /**
-     * Returns if the level is inside the given level
-     * @param {Level} level the container level
-     */
-    isInside(level) {
-        return Level.contains(level, this);
-    }
-
-    /**
-     * Returns if the level is inside the given level
-     * @param {Level} level the container level
-     */
-    contains(level) {
-        return Level.contains(this, level);
+        throw Error(`Cannot parse following level: ${str}`);
     }
 
 
     /**
      * Returns if a level is contained in another
-     * @param {Level} container The container level
-     * @param {Level} targeted The targeted level
+     * @param {null|number|[number, number]} container The container level
+     * @param {null|number|[number, number]} targeted The targeted level
      */
     static contains(container, targeted) {
+        if (this.VERIFY_TYPING) {
+            this.checkType(container);
+            this.checkType(targeted);
+        }
 
+        // Covers null and number
         if (container === targeted) {
             return true;
         }
 
-        if (!container || !targeted) {
-            return false;
-        }
-
-        if (!container.isRange) {
-            if (targeted.isRange) {
-                return false;
+        if (Array.isArray(container)) {
+            if (Array.isArray(targeted)) {
+                return container[0] <= targeted[0] && container[1] >= targeted[1];
             }
-            return container.val === targeted.val;
+            return container[0] <= targeted && container[1] >= targeted;
         }
-
-        return container.up >= (targeted.isRange ? targeted.up : targeted.val)
-            && container.low <= (targeted.isRange ? targeted.low : targeted.val);
+        return container <= targeted[0] && container >= targeted[1];
     }
 
     /**
      * Retrieve the intersection of two levels
-     * @param {Level} other The other level
+     * @param {null|number|[number, number]} first The first level
+     * @param {null|number|[number, number]} second The second level
+     * @returns {null|number|[number, number]}
      */
-    intersect(other) {
-        return Level.intersect(this, other);
-    }
+    static intersection(first, second) {
 
-    /**
-     * Retrieve the intersection of two levels
-     * @param {Level} first The first level
-     * @param {Level} second The second level
-     */
-    static intersect(first, second) {
+        if (this.VERIFY_TYPING) {
+            this.checkType(first);
+            this.checkType(second);
+        }
 
-        if (first === second) {
-            if (first instanceof Level) {
-                return first.clone();
-            }
+        if (first === null || second === null) {
             return null;
         }
 
-        if (!second) {
-            return null;
+        if (this.equals(first, second)) {
+            return this.clone(first);
         }
 
-        if (!first) {
-            return null;
+        if (typeof first === 'number' && typeof second === 'number') {
+            return first === second ? first : null;
         }
 
-        if (first.isRange && !second.isRange) {
-            if (first.contains(second)) {
-                return second.clone();
+        if (Array.isArray(first) && !Array.isArray(second)) {
+            if (this.contains(first, second)) {
+                return second;
             }
             return null;
         }
-        if (!first.isRange && second.isRange) {
-            if (second.contains(first)) {
-                return first.clone();
+        if (!Array.isArray(first) && Array.isArray(second)) {
+            if (this.contains(second, first)) {
+                return first;
             }
             return null;
         }
-        if (first.isRange && second.isRange) {
-            const up = Math.min(first.up, second.up);
-            const low = Math.max(first.low, second.low);
-            if (up < low) {
-                return null;
-            }
-            return new Level(low, up);
+
+        // There are two ranges
+        const low = Math.max(first[0], second[0]);
+        const up = Math.min(first[1], second[1]);
+        if (up === low) {
+            return up;
         }
-        return first.val === second.val ? first : null;
+        return up < low ? null : [low, up];
     }
 
     /**
-     * Retrieve the union of two levels
-     * @param {Level} other The other level
-     */
-    union(other) {
-        return Level.union(this, other);
+    * 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 (this.VERIFY_TYPING) {
+            this.checkType(first);
+            this.checkType(second);
+        }
+
+        if (first === null && second === null) {
+            return true;
+        }
+
+        return this.intersection(first, second) !== null;
     }
 
     /**
      * Retrieve the union of two levels
-     * @param {Level} other The other level
+     * @param {null|number|[number, number]} first The first level
+     * @param {null|number|[number, number]} second The scond level
+     * @returns {null|number|[number, number]}
      */
     static union(first, second) {
 
+        if (this.VERIFY_TYPING) {
+            this.checkType(first);
+            this.checkType(second);
+        }
+
         if (first === second) {
-            if (first instanceof Level) {
-                return first.clone();
-            }
-            return null;
+            return this.clone(first);
         }
 
-        if (!second) {
-            return first.clone();
+        if (second === null) {
+            return this.clone(first);
         }
 
-        if (!first) {
-            return second.clone();
+        if (first === null) {
+            return this.clone(second);
         }
 
         let low, up;
-        if (!first.isRange && !second.isRange) {
-            low = Math.min(first.val, second.val);
-            up = Math.max(first.val, second.val);
-        } else if (first.isRange && !second.isRange) {
-            low = Math.min(first.low, second.val);
-            up = Math.max(first.up, second.val);
-        } else if (!first.isRange && second.isRange) {
-            low = Math.min(second.low, first.val);
-            up = Math.max(second.up, first.val);
+        if (!Array.isArray(first) && !Array.isArray(second)) {
+            low = Math.min(first, second);
+            up = Math.max(first, second);
+        } else if (Array.isArray(first) && !Array.isArray(second)) {
+            low = Math.min(first[0], second);
+            up = Math.max(first[1], second);
+        } else if (!Array.isArray(first) && Array.isArray(second)) {
+            low = Math.min(second[0], first);
+            up = Math.max(second[1], first);
         } else {
-            /* if (first.isRange && second.isRange) */
-            low = Math.min(second.low, first.low);
-            up = Math.max(second.up, first.up);
+            /* if (Array.isArray(first) && Array.isArray(second)) */
+            low = Math.min(second[0], first[0]);
+            up = Math.max(second[1], first[1]);
         }
 
         if (low === up) {
-            return new Level(low);
+            return low;
         }
-        return new Level(low, up);
+        return [low, up];
     }
 
-    multiplyBy(factor) {
-        if (this.isRange) {
-            this.low *= factor;
-            this.up *= factor;
-        } else {
-            this.val *= factor;
+    /**
+     * 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 (this.VERIFY_TYPING) {
+            this.checkType(level);
         }
-        return this;
+
+        return Array.isArray(level) ? [level[0] * factor, level[1] * factor] : level * factor;
     }
 
-    toString() {
-        return this.isRange ? this.low + ';' + this.up : String(this.val);
+    /**
+     * @param {null|number|[number, number]} level
+     * @returns {string|null}
+     */
+    static toString(level) {
+        if (this.VERIFY_TYPING) {
+            this.checkType(level);
+        }
+        if (level === null) {
+            return null;
+        }
+        return Array.isArray(level) ? level[0] + ';' + level[1] : String(level);
     }
 
-    static equalsTo(first, second) {
+    /**
+     * @param {null|number|[number, number]} first
+     * @param {null|number|[number, number]} second
+     * @returns {boolean}
+     */
+    static equals(first, second) {
+
+        if (this.VERIFY_TYPING) {
+            this.checkType(first);
+            this.checkType(second);
+        }
 
         if (first === second) {
             return true;
         }
-        if (!first && !second) {
-            return true;
-        }
-        if (!first && second) {
-            return false;
-        }
-        if (first && !second) {
-            return false;
-        }
-        if (!first.isRange && second.isRange) {
-            return false;
-        }
-        if (first.isRange && !second.isRange) {
-            return false;
-        }
-        if (first.isRange && second.isRange) {
-            return first.low === second.low && first.up === second.up;
+
+        if (Array.isArray(first) && Array.isArray(second)) {
+            return first[0] === second[0] && first[1] === second[1];
         }
-        // !first.isRange && !second.isRange
-        return first.val === second.val;
 
+        return false;
     }
 
+    /**
+     * @param {null|number|[number, number]} first
+     * @param {null|number|[number, number]} second
+     * @returns {null|number}
+     */
     static diff(first, second) {
 
+        if (this.VERIFY_TYPING) {
+            this.checkType(first);
+            this.checkType(second);
+        }
+
         if (first === null || second === null) {
             return null;
         }
 
-        if (!first.isRange && !second.isRange) {
-            return second.val - first.val;
+        if (!Array.isArray(first) && !Array.isArray(second)) {
+            return second - first;
         }
 
-        if (first.isRange && !second.isRange) {
-            if (first.low === second.val) {
-                return second.val - first.up;
+        if (Array.isArray(first) && !Array.isArray(second)) {
+            if (first[0] === second) {
+                return second - first[1];
             }
-            if (first.up === second.val) {
-                return second.val - first.low;
+            if (first[1] === second) {
+                return second - first[0];
             }
             return null;
         }
 
-        if (second.isRange && !first.isRange) {
-            if (first.val === second.low) {
-                return second.up - first.val;
+        if (Array.isArray(second) && !Array.isArray(first)) {
+            if (first === second[0]) {
+                return second[1] - first;
             }
-            if (first.val === second.up) {
-                return second.low - first.val;
+            if (first === second[1]) {
+                return second[0] - first;
             }
             return null;
         }
 
-        if (Level.equalsTo(first, second)) {
+        if (Level.equals(first, second)) {
             return 0;
         }
 
         return null;
     }
 
+    /**
+     * @param {null|{isRange: boolean, val?: number, low?: number, up?: number}} legacyLevel
+     * @deprecated
+     */
+    static fromLegacy(legacyLevel) {
+        if (legacyLevel === null) {
+            return null;
+        }
+        if (legacyLevel.isRange) {
+            return [legacyLevel.low, legacyLevel.up];
+        }
+        return legacyLevel.val;
+    }
 }
 
 /**
@@ -358,7 +400,7 @@ class Coordinates {
     /** @type {Number|null} */
     _alt = null;
 
-    /** @type {Level|null} */
+    /** @type {null|number|[number, number]} */
     _level = null;
 
     /** @type {[Number, Number, Number]|null} */
@@ -370,7 +412,7 @@ class Coordinates {
      * @param {Number} lat
      * @param {Number} lng
      * @param {?(Number|null)} alt
-     * @param {?(Level|null)} level
+     * @param {?(null|number|[number, number])} level
      */
     constructor(lat, lng, alt = null, level = null) {
         this.lat = lat;
@@ -409,7 +451,7 @@ class Coordinates {
         return this._alt;
     }
 
-    /** @type {Level|null} */
+    /** @type {null|number|[number, number]} */
     get level() {
         return this._level;
     }
@@ -460,16 +502,10 @@ class Coordinates {
         this._ecef = null;
     }
 
-    /** @type {Level|null} */
+    /** @type {null|number|[number, number]} */
     set level(level) {
-        if (level instanceof Level) {
-            this._level = level;
-        } else {
-            if (typeof level !== 'undefined' && level !== null) {
-                throw new Error('level argument is not a Level object');
-            }
-            this._level = null;
-        }
+        Level.checkType(level);
+        this._level = level;
     }
 
     /**
@@ -478,8 +514,8 @@ class Coordinates {
      */
     clone() {
         const output = new Coordinates(this.lat, this.lng, this.alt);
-        if (this.level) {
-            output.level = this.level.clone();
+        if (this.level !== null) {
+            output.level = Level.clone(this.level);
         }
         return output;
     }
@@ -497,7 +533,7 @@ class Coordinates {
      * @param {Number} eps latitude and longitude epsilon in degrees (default: 1e-8 [~1mm at lat=0])
      * @param {Number} epsAlt altitude epsilon in meters (default: 1e-3 [= 1mm])
      */
-    static equalsTo(pos1, pos2, eps = Constants.EPS_DEG_MM, epsAlt = Constants.EPS_MM) {
+    static equals(pos1, pos2, eps = Constants.EPS_DEG_MM, epsAlt = Constants.EPS_MM) {
 
         // Handle null comparison
         if (pos1 === null && pos1 === pos2) {
@@ -513,15 +549,15 @@ class Coordinates {
             && (pos1.alt === pos2.alt
                 || pos1.alt !== null && pos2.alt !== null
                 && Math.abs(pos2.alt - pos1.alt) < epsAlt)
-            && Level.equalsTo(pos1.level, pos2.level);
+            && Level.equals(pos1.level, pos2.level);
     }
 
     /**
      * @param {Coordinates} other
      * @returns {!Boolean}
      */
-    equalsTo(other) {
-        return Coordinates.equalsTo(this, other);
+    equals(other) {
+        return Coordinates.equals(this, other);
     }
 
     /**
@@ -738,7 +774,7 @@ class Coordinates {
             alt = (p1.alt + p2.alt) / 2;
         }
         const projection = new Coordinates(poseCoordinates.lat, poseCoordinates.lng,
-            alt, Level.intersect(p1.level, p2.level));
+            alt, Level.intersection(p1.level, p2.level));
 
         if (Math.abs((p1.distanceTo(p2) - p1.distanceTo(projection) - p2.distanceTo(projection))) > Constants.EPS_MM) {
             return null;
@@ -760,7 +796,7 @@ class Coordinates {
             str += ', ' + this._alt.toFixed(2);
         }
         if (this._level !== null) {
-            str += ', [' + this._level.toString() + ']';
+            str += ', [' + Level.toString(this._level) + ']';
         }
         str += ']';
         return str;
@@ -778,7 +814,24 @@ class Coordinates {
             output.alt = this.alt;
         }
         if (this.level !== null) {
-            output.level = this.level.toString();
+            output.level = this.level;
+        }
+        return output;
+    }
+
+    /**
+     * @returns {!Object}
+     */
+    toLegacyJson() {
+        const output = {
+            lat: this.lat,
+            lng: this.lng
+        };
+        if (this.alt !== null) {
+            output.alt = this.alt;
+        }
+        if (this.level !== null) {
+            output.level = Level.toString(this.level);
         }
         return output;
     }
@@ -788,7 +841,11 @@ class Coordinates {
      * @returns {!Coordinates}
      */
     static fromJson(json) {
-        return new Coordinates(json.lat, json.lng, json.alt, Level.fromString(json.level));
+        if (typeof json.level === 'string') {
+            Logger.warn('Still using legacy level format. Please update your project.');
+            return new Coordinates(json.lat, json.lng, json.alt, Level.fromString(json.level));
+        }
+        return new Coordinates(json.lat, json.lng, json.alt, json.level);
     }
 
     /**
@@ -800,7 +857,22 @@ class Coordinates {
             output.push(this.alt);
         }
         if (this.level !== null) {
-            output.push(this.level.toString());
+            output.push(this.level);
+        }
+        return output;
+    }
+
+    /**
+     * @returns {!Object}
+     * @deprecated
+     */
+    toLegacyCompressedJson() {
+        const output = [this.lat, this.lng];
+        if (this.alt !== null || this.level !== null) {
+            output.push(this.alt);
+        }
+        if (this.level !== null) {
+            output.push(Level.toString(this.level));
         }
         return output;
     }
@@ -810,6 +882,26 @@ class Coordinates {
      * @returns {!Coordinates}
      */
     static fromCompressedJson(json) {
+        const coords = new Coordinates(json[0], json[1]);
+        if (json.length > 2) {
+            coords.alt = json[2];
+        }
+        if (json.length > 3) {
+            if (typeof json[3] === 'string') {
+                Logger.warn('Still using legacy level format. Please update your project.');
+                coords.level = Level.fromString(json[3]);
+            } else {
+                coords.level = json[3];
+            }
+        }
+        return coords;
+    }
+
+    /**
+     * @param {!Object} json
+     * @returns {!Coordinates}
+     */
+    static fromLegacyCompressedJson(json) {
         const coords = new Coordinates(json[0], json[1]);
         if (json.length > 2) {
             coords.alt = json[2];
@@ -908,7 +1000,7 @@ class UserPosition extends Coordinates {
      * @param {Number} eps latitude and longitude epsilon in degrees (default: 1e-8 [~1mm at lat=0])
      * @param {Number} epsAlt altitude epsilon in meters (default: 1e-3 [= 1mm])
      */
-    static equalsTo(pos1, pos2, eps = Constants.EPS_DEG_MM, epsAlt = Constants.EPS_MM) {
+    static equals(pos1, pos2, eps = Constants.EPS_DEG_MM, epsAlt = Constants.EPS_MM) {
 
         // Handle null comparison
         if (pos1 === null && pos1 === pos2) {
@@ -919,7 +1011,7 @@ class UserPosition extends Coordinates {
             return false;
         }
 
-        if (!super.equalsTo(pos1, pos2, eps, epsAlt)) {
+        if (!super.equals(pos1, pos2, eps, epsAlt)) {
             return false;
         }
 
@@ -928,8 +1020,8 @@ class UserPosition extends Coordinates {
             && pos1.bearing === pos2.bearing;
     }
 
-    equalsTo(other) {
-        return UserPosition.equalsTo(this, other);
+    equals(other) {
+        return UserPosition.equals(this, other);
     }
 
 
@@ -1044,14 +1136,14 @@ function trimRoute(route, startPosition = route[0], length = Number.MAX_VALUE) {
         const p1 = route[currentPointIndex - 1];
         const p2 = route[currentPointIndex];
 
-        if (Coordinates.equalsTo(startPosition, p1)) {
+        if (Coordinates.equals(startPosition, p1)) {
             newRoute.push(p1);
             previousPoint = p1;
             break;
         }
 
         const proj = startPosition.getSegmentProjection(p1, p2);
-        if (proj && Coordinates.equalsTo(startPosition, proj) && !proj.equalsTo(p2)) {
+        if (proj && Coordinates.equals(startPosition, proj) && !proj.equals(p2)) {
             newRoute.push(proj);
             previousPoint = proj;
             break;
@@ -1089,7 +1181,7 @@ function trimRoute(route, startPosition = route[0], length = Number.MAX_VALUE) {
  */
 function simplifyRoute(coords, precisionAngle = deg2rad(5)) {
 
-    const isClosed = (coords[0].equalsTo(coords[coords.length - 1]));
+    const isClosed = (coords[0].equals(coords[coords.length - 1]));
 
     let newRoute = coords.slice(0, coords.length - (isClosed ? 1 : 0));
 
@@ -1336,13 +1428,13 @@ class BoundingBox {
         return this.northEast.lat;
     }
 
-    static equalsTo(bb1, bb2) {
-        return Coordinates.equalsTo(bb1.northEast, bb2.northEast)
-            && Coordinates.equalsTo(bb1.southWest, bb2.southWest);
+    static equals(bb1, bb2) {
+        return Coordinates.equals(bb1.northEast, bb2.northEast)
+            && Coordinates.equals(bb1.southWest, bb2.southWest);
     }
 
-    equalsTo(other) {
-        return BoundingBox.equalsTo(this, other);
+    equals(other) {
+        return BoundingBox.equals(this, other);
     }
 
     /**
@@ -1478,7 +1570,7 @@ class RelativePosition {
      * @param {RelativePosition} pos2 position 2
      * @param {Number} eps x, y, z epsilon in meters (default: 1e-3 [= 1mm])
      */
-    static equalsTo(pos1, pos2, eps = Constants.EPS_MM) {
+    static equals(pos1, pos2, eps = Constants.EPS_MM) {
 
         // Handle null comparison
         if (pos1 === null && pos1 === pos2) {
@@ -1497,8 +1589,8 @@ class RelativePosition {
             && pos1.bearing === pos2.bearing;
     }
 
-    equalsTo(other) {
-        return RelativePosition.equalsTo(this, other);
+    equals(other) {
+        return RelativePosition.equals(this, other);
     }
 
 
@@ -1715,7 +1807,7 @@ class Attitude {
      * @param {Attitude} att1 attitude 1
      * @param {Attitude} att2 attitude 2
      */
-    static equalsTo(att1, att2) {
+    static equals(att1, att2) {
 
         // Handle null comparison
         if (att1 === null && att1 === att2) {
@@ -1731,15 +1823,15 @@ class Attitude {
             return true;
         }
 
-        return Quaternion.equalsTo(att1.quaternion, att2.quaternion);
+        return Quaternion.equals(att1.quaternion, att2.quaternion);
     }
 
     /**
      * @param {Attitude} other
      * @returns {boolean}
      */
-    equalsTo(other) {
-        return Attitude.equalsTo(this, other);
+    equals(other) {
+        return Attitude.equals(this, other);
     }
 
     /**
@@ -1864,7 +1956,7 @@ class AbsoluteHeading {
      * @param {AbsoluteHeading} heading1 heading 1
      * @param {AbsoluteHeading} heading2 heading 2
      */
-    static equalsTo(heading1, heading2) {
+    static equals(heading1, heading2) {
 
         // Handle null comparison
         if (heading1 === null && heading1 === heading2) {
@@ -1878,8 +1970,8 @@ class AbsoluteHeading {
         return Math.abs(heading1.heading - heading2.heading) < 1e-8;
     }
 
-    equalsTo(other) {
-        return AbsoluteHeading.equalsTo(this, other);
+    equals(other) {
+        return AbsoluteHeading.equals(this, other);
     }
 
     toJson() {
@@ -1964,8 +2056,8 @@ class GraphNode {
      * @param {GraphNode} other
      * @returns {boolean}
      */
-    equalsTo(other) {
-        return this.coords.equalsTo(other.coords)
+    equals(other) {
+        return this.coords.equals(other.coords)
             && this.builtFrom === other.builtFrom;
     }
 
@@ -1996,16 +2088,16 @@ class GraphNode {
         return new GraphNode(Coordinates.fromCompressedJson(json));
     }
 
-    generateLevelFromEdges() {
+    _generateLevelFromEdges() {
         let tmpLevel = null;
         for (let i = 0; i < this.edges.length; i++) {
             const edge = this.edges[i];
-            if (edge.level) {
-                if (!tmpLevel) {
-                    tmpLevel = edge.level.clone();
+            if (edge.level !== null) {
+                if (tmpLevel === null) {
+                    tmpLevel = Level.clone(edge.level);
                 } else {
-                    tmpLevel = tmpLevel.intersect(edge.level);
-                    if (!tmpLevel) {
+                    tmpLevel = Level.intersection(tmpLevel, edge.level);
+                    if (tmpLevel === null) {
                         Logger.error('Error: Something bad happend during parsing: We cannot retrieve node level from adjacent ways: ' + this.coords);
                         return false;
                     }
@@ -2020,9 +2112,9 @@ class GraphNode {
     /**
      * We suppose generateLevelFromEdges() was called before
      */
-    inferNodeLevelByRecursion() {
+    _inferNodeLevelByRecursion() {
         const { level } = this.coords;
-        if (!level || !level.isRange) {
+        if (level === null || !Level.isRange(level)) {
             return true;
         }
 
@@ -2038,16 +2130,17 @@ class GraphNode {
          * The result of this method is an union of all single level nodes found.
          * @param {GraphNode} node node to explore
          * @param {GraphNode[]} visitedNodes list of visited nodes
+         * @returns {null|number|[number, number]}
          */
         const lookForLevel = (node, visitedNodes) => {
 
             visitedNodes.push(node);
 
-            if (!node.coords.level) {
+            if (node.coords.level === null) {
                 return null;
             }
 
-            if (!node.coords.level.isRange) {
+            if (!Level.isRange(node.coords.level)) {
                 return node.coords.level;
             }
 
@@ -2065,8 +2158,8 @@ class GraphNode {
         const othersLevels = lookForLevel(this, []);
 
         if (othersLevels !== null) {
-            if (!othersLevels.isRange) {
-                this.coords.level = new Level(othersLevels.val === level.low ? level.up : level.low);
+            if (!Level.isRange(othersLevels)) {
+                this.coords.level = othersLevels === level[0] ? level[1] : level[0];
                 return true;
             }
             Logger.warn('Level of: ' + this.coords.toString() + ' cannot be decided');
@@ -2079,9 +2172,9 @@ class GraphNode {
     /**
      * We suppose generateLevelFromEdges() was called before
      */
-    inferNodeLevelByNeighboors() {
+    _inferNodeLevelByNeighboors() {
         const { level } = this.coords;
-        if (!level || !level.isRange) {
+        if (level === null || !Level.isRange(level)) {
             return true;
         }
 
@@ -2092,8 +2185,8 @@ class GraphNode {
             tmpLevel = Level.union(otherNode.coords.level, tmpLevel);
         }
 
-        if (tmpLevel === null || !tmpLevel.isRange) {
-            this.coords.level = new Level(tmpLevel.val === level.low ? level.up : level.low);
+        if (tmpLevel === null || !Level.isRange(tmpLevel)) {
+            this.coords.level = tmpLevel === level[0] ? level[1] : level[0];
         }
 
         return true;
@@ -2103,7 +2196,7 @@ class GraphNode {
      * Set node.io to true for nodes that make the link between
      * indoor and outdoor edges
      */
-    checkIO() {
+    _checkIO() {
         this.io = this._coords.level !== null
             && this.edges.some(edge => edge.level === null);
         return true;
@@ -2113,7 +2206,7 @@ class GraphNode {
      * @param {GraphNode[]} nodes
      */
     static generateNodesLevels(nodes) {
-        const success = nodes.reduce((acc, node) => acc && node.generateLevelFromEdges(), true);
+        const success = nodes.reduce((acc, node) => acc && node._generateLevelFromEdges(), true);
         if (!success) {
             return false;
         }
@@ -2122,12 +2215,12 @@ class GraphNode {
         // (e.g stairs without network at one of its bounds)
         // To infer this node level, we use inferNodeLevelByRecursion()
         const res = nodes.reduce((acc, node) => acc
-            && node.inferNodeLevelByNeighboors()
-            && node.inferNodeLevelByRecursion()
+            && node._inferNodeLevelByNeighboors()
+            && node._inferNodeLevelByRecursion()
         , true);
 
         // Finally define nodes that are links between indoor and outdoor
-        nodes.forEach(node => node.checkIO());
+        nodes.forEach(node => node._checkIO());
 
         return res;
     }
@@ -2148,7 +2241,7 @@ class GraphEdge {
     /** @type {GraphNode<T>} */
     _node2 = null;
 
-    /** @type {?Level} */
+    /** @type {null|number|[number, number]} */
     _level = null;
 
     /** @type {?number} */
@@ -2169,7 +2262,7 @@ class GraphEdge {
     /**
      * @param {!GraphNode} node1
      * @param {!GraphNode} node2
-     * @param {?Level} level
+     * @param {?(null|number|[number, number])} level
      * @param {?T} builtFrom
      * @param {?string} name
      */
@@ -2224,21 +2317,15 @@ class GraphEdge {
         this._computedSizeAndBearing = false;
     }
 
-    /** @type {?Level} */
+    /** @type {null|number|[number, number]} */
     get level() {
         return this._level;
     }
 
-    /** @type {?Level} */
+    /** @type {null|number|[number, number]} */
     set level(level) {
-        if (level instanceof Level) {
-            this._level = level;
-        } else {
-            if (typeof level !== 'undefined' && level !== null) {
-                throw new Error('level argument is not a Level object');
-            }
-            this._level = null;
-        }
+        Level.checkType(level);
+        this._level = level;
     }
 
     /**
@@ -2273,7 +2360,7 @@ class GraphEdge {
      * @param {GraphEdge<T>} other
      * @returns {boolean}
      */
-    equalsTo(other) {
+    equals(other) {
 
         if (this === other) {
             return true;
@@ -2283,9 +2370,9 @@ class GraphEdge {
             return false;
         }
 
-        return other.node1.equalsTo(this.node1)
-            && other.node2.equalsTo(this.node2)
-            && Level.equalsTo(other.level, this.level)
+        return other.node1.equals(this.node1)
+            && other.node2.equals(this.node2)
+            && Level.equals(other.level, this.level)
             && other.isOneway === this.isOneway
             && other.builtFrom === this.builtFrom;
     }
@@ -2351,7 +2438,7 @@ class Network {
      * @returns {?GraphNode<T>}
      */
     getNodeByCoords(coords) {
-        return this.nodes.find(node => node.coords.equalsTo(coords));
+        return this.nodes.find(node => node.coords.equals(coords));
     }
 
     /**
@@ -2427,7 +2514,7 @@ class Network {
                     this.nodes.indexOf(edge.node2)
                 ];
                 if (edge.level !== null) {
-                    output.push(edge.level.toString());
+                    output.push(edge.level);
                 }
                 if (edge.isOneway) {
                     if (edge.level === null) {
@@ -2456,7 +2543,7 @@ class Network {
                 network.nodes[jsonEdge[1]]
             );
             if (jsonEdge.length > 2 && jsonEdge[2] !== null) {
-                edge.level = Level.fromString(jsonEdge[2]);
+                edge.level = jsonEdge[2];
             }
             if (jsonEdge.length > 3 && jsonEdge[3]) {
                 edge.isOneway = true;
@@ -2478,7 +2565,7 @@ class Network {
         const network = new Network();
 
         const getOrCreateNode = coords =>
-            network.nodes.find(_coords => _coords.equalsTo(coords)) || new GraphNode(coords);
+            network.nodes.find(_coords => _coords.equals(coords)) || new GraphNode(coords);
 
 
         const createEdgeFromNodes = (node1, node2) =>
@@ -2512,7 +2599,7 @@ class Network {
     getEdgesAtLevel(targetLevel, useMultiLevelEdges = true) {
         return this.edges.filter(
             ({ level }) => useMultiLevelEdges
-                ? Level.intersect(targetLevel, level) !== null
+                ? Level.intersect(targetLevel, level)
                 : Level.contains(targetLevel, level)
         );
     }
@@ -2607,37 +2694,29 @@ class MapMatching {
      */
     _shouldProjectOnEdgeAndNodes(edge, location, useBearing, useMultiLevelSegments, acceptEdgeFn) {
 
+        // ignore projections if edge is not accepted
         if (!acceptEdgeFn(edge)) {
-            // if edge selection is not verified
             return [false, false, false];
         }
 
-        let checkNode1 = true;
-        let checkNode2 = true;
-        let checkEdge = true;
+        // First, check if levels intersects
+        let checkEdge = Level.intersect(location.level, edge.level);
+        let checkNode1 = Level.intersect(location.level, edge.node1.coords.level);
+        let checkNode2 = Level.intersect(location.level, edge.node2.coords.level);
 
-        if (
-            // Verify if edge level only if one of both is defined
-            (location.level || edge.level)
-            && (
-                // if edge level intersect location level
-                !Level.intersect(location.level, edge.level)
-                // ignore MultiLevelSegments if option used
-                || (!useMultiLevelSegments && edge.level && edge.level.isRange)
-            )) {
-            checkEdge = false;
-        }
+        // Second, in case of IO nodes, accept matching if location's level is null
+        checkNode1 ||= edge.node1.io && location.level === null;
+        checkNode2 ||= edge.node2.io && location.level === null;
 
-        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 && !location.level)) {
-            checkNode2 = false;
+        // Third, check if level is a range if useMultiLevelSegments is false
+        if (!useMultiLevelSegments) {
+            checkEdge &&= !Level.isRange(edge.level);
+            checkNode1 &&= !Level.isRange(edge.node1.coords.level);
+            checkNode2 &&= !Level.isRange(edge.node2.coords.level);
         }
 
+        // Finally, check edges bearing if option is used
         if (useBearing) {
-            // if mapmatching bearing is enabled do not use nodes matching
             if (checkEdge) {
                 // condition for optimisation
                 const diffAngle = diffAngleLines(edge.bearing, location.bearing);
@@ -2646,6 +2725,7 @@ class MapMatching {
                     checkEdge = false;
                 }
             }
+            // if mapmatching bearing is enabled do not use nodes matching
             checkNode1 = false;
             checkNode2 = false;
         }
@@ -2661,7 +2741,22 @@ class MapMatching {
     static _assignLatLngLevel(fromCoordinates, toCoordinates) {
         toCoordinates.lat = fromCoordinates.lat;
         toCoordinates.lng = fromCoordinates.lng;
-        toCoordinates.level = fromCoordinates.level;
+        toCoordinates.level = Level.clone(fromCoordinates.level);
+    }
+
+    /**
+     * IO Nodes 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 node and a location with
+     * a null level is required.
+     *
+     * @param {Coordinates} projection
+     * @param {Coordinates} location
+     * @param {GraphNode} projectionNode
+     */
+    static _handleLevelsWithIONodes(projection, location, projectionNode) {
+        if (location.level === null && projectionNode.io) {
+            projection.level = null;
+        }
     }
 
     /**
@@ -2669,18 +2764,20 @@ class MapMatching {
      * @param {Coordinates} _projection
      */
     static _updateProjectionLevelFromEdge = (_edge, _projection) => {
-        if (_edge.level) {
-            _projection.level = _edge.level.clone();
-        }
+        _projection.level = Level.clone(_edge.level);
     };
 
     /**
+     * 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).
+     *
      * @param {!Coordinates} location
      * @param {boolean} useDistance
      * @param {boolean} useBearing
      * @param {boolean} useMultiLevelSegments
      * @param {function} acceptEdgeFn
-     * @returns {GraphProjection}
+     * @returns {?GraphProjection}
      */
     getProjection(location, useDistance = false, useBearing = false,
         useMultiLevelSegments = true, acceptEdgeFn = () => true) {
@@ -2694,22 +2791,29 @@ class MapMatching {
         }
 
         if (useBearing && (!location.bearing || !this._maxAngleBearing)) {
+            // If useBearing is true and bearing is not set in coordinates, return null
             return null;
         }
 
+        // Build a new GraphProjection object from parameters
         const projection = new GraphProjection();
         projection.origin = location;
         projection.distanceFromNearestElement = Number.MAX_VALUE;
         projection.projection = location.clone();
 
+        // Define a function to know if a projection is better than the current one
         const isProjectionBetter = (distanceOfNewProjection) => {
             return distanceOfNewProjection < projection.distanceFromNearestElement
                 && (!useDistance || distanceOfNewProjection <= this._maxDistance);
         };
 
-        for (let i = 0; i < this.network.edges.length; i++) {
-            const edge = this.network.edges[i];
+        // Loop on all the network edges
+        // Each time a better projection is found (see isProjectionBetter()),
+        //  the current projection is replaced
+        for (const edge of this.network.edges) {
 
+            // Check if the specified edge and its nodes can be used for projection. See the
+            // documentation of the corresponding function for more information.
             const [checkEdge, checkNode1, checkNode2] = this._shouldProjectOnEdgeAndNodes(
                 edge, location, useBearing, useMultiLevelSegments, acceptEdgeFn);
 
@@ -2720,10 +2824,9 @@ class MapMatching {
                     projection.distanceFromNearestElement = distNode1;
                     projection.nearestElement = edge.node1;
                     MapMatching._assignLatLngLevel(edge.node1.coords, projection.projection);
-                    MapMatching._updateProjectionLevelFromEdge(edge, projection.projection);
+                    MapMatching._handleLevelsWithIONodes(projection.projection, location, edge.node1);
 
-                    if (distNode1 <= Constants.EPS_MM
-                        && location.level === edge.node1.coords.level) {
+                    if (distNode1 <= Constants.EPS_MM) {
                         break;
                     }
                 }
@@ -2733,14 +2836,12 @@ class MapMatching {
 
                 const distNode2 = location.distanceTo(edge.node2.coords);
                 if (isProjectionBetter(distNode2) || distNode2 <= Constants.EPS_MM) {
-
                     projection.distanceFromNearestElement = distNode2;
                     projection.nearestElement = edge.node2;
                     MapMatching._assignLatLngLevel(edge.node2.coords, projection.projection);
-                    MapMatching._updateProjectionLevelFromEdge(edge, projection.projection);
+                    MapMatching._handleLevelsWithIONodes(projection.projection, location, edge.node2);
 
-                    if (distNode2 <= Constants.EPS_MM
-                        && location.level === edge.node2.coords.level) {
+                    if (distNode2 <= Constants.EPS_MM) {
                         break;
                     }
                 }
@@ -2903,11 +3004,11 @@ class GraphRouterOptions {
  */
 class GraphRouter {
 
-    /** @type {!Network<T>} */
+    /** @type {!(Network<T>)} */
     _network;
 
     /**
-     * @param {!Network<T>} network
+     * @param {!(Network<T>)} network
      */
     constructor(network) {
         this._network = network;
@@ -2954,9 +3055,9 @@ class GraphRouter {
             if (!proj) {
                 let message = `Point ${point.toString()} is too far from the network `
                     + `> ${this._mapMatching.maxDistance.toFixed(0)} meters.`;
-                if (point.level) {
+                if (point.level !== null) {
                     message += ' If it is a multi-level map, please verify if you have'
-                        + ` a network at level ${point.level.toString()}.`;
+                        + ` a network at level ${Level.toString(point.level)}.`;
                 }
                 throw new NoRouteFoundError(start, end, message);
             }