@wemap/positioning 2.0.0 → 2.2.0

package/src/index.js

@@ -1,6 +1,6 @@
+import InclinationProvider from './providers/computed/InclinationProvider';
 import PositioningHandler from './PositioningHandler';
-import AttitudeHandler from '../src.old/attitude/AttitudeHandler';
 
 export {
-    AttitudeHandler, PositioningHandler
+    InclinationProvider, PositioningHandler
 };

package/src/providers/Constants.js

@@ -0,0 +1,5 @@
+const Constants = {
+    DEFAULT_ALTITUDE: 1.6
+};
+
+export default Constants;

package/src/providers/FakeAbsolutePositionProvider.js

@@ -0,0 +1,56 @@
+import {
+    WGS84, Attitude
+} from '@wemap/geo';
+import Provider from './Provider';
+import EventType from '../events/EventType';
+
+
+/**
+ * @private
+ */
+class FakeAbsolutePositionProvider extends Provider {
+
+    /**
+     * @override
+     */
+    static get displayName() {
+        return 'FakeAbsolutePosition';
+    }
+
+    /**
+     * @override
+     */
+    static get eventsType() {
+        return [EventType.AbsoluteAttitude, EventType.AbsolutePosition];
+    }
+
+    /**
+     * @override
+     */
+    startInternal() {
+
+        this.interval = setInterval(() => {
+            this.notify(
+                this.createEvent(EventType.AbsoluteAttitude, new Attitude([1, 0, 0, 0])),
+                this.createEvent(EventType.AbsolutePosition, new WGS84(45, 5))
+            );
+        }, 1000);
+
+        return Promise.resolve();
+    }
+
+    /**
+     * @override
+     */
+    stopInternal() {
+
+        if (this.interval) {
+            clearInterval(this.interval);
+            this.interval = null;
+        }
+        return Promise.resolve();
+    }
+
+}
+
+export default FakeAbsolutePositionProvider;

package/src/providers/Provider.js

@@ -0,0 +1,230 @@
+import noop from 'lodash.noop';
+
+import EventType from '../events/EventType';
+import ProviderEvent from '../events/ProviderEvent';
+import Logger from '@wemap/logger';
+import ProviderError from '../events/ProviderError';
+import ProvidersLogger from './ProvidersLogger';
+import MissingNativeInterfaceError from '../errors/MissingNativeInterfaceError';
+
+let uniqueId = 1;
+
+/**
+ * A provider is a meta class to define an entity which can be
+ * started / stopped and provides a data of {@link ProviderEvent#DataType}
+ */
+class Provider {
+
+    static DEFAULT_NAME = 'Unknown';
+    static DEFAULT_OPTIONS = {
+        stopOnError: true,
+        checkAvailabilityOnStart: true
+    };
+
+    static State = {
+        STARTING: 0,
+        STARTED: 1,
+        STOPPPED: 2
+    };
+
+    static Warnings = {
+        ALREADY_STARTED: 'Provider already started',
+        ALREADY_STOPPED: 'Provider already stopped'
+    }
+
+    state = Provider.State.STOPPPED;
+
+    /**
+     * Provider constructor
+     * @param {Function} onEvent a callback which will receive events
+     * @param {Function} onError a callback when an error happen
+     * @param {Object} options provider options
+     */
+    constructor(onEvent, onError, options) {
+        this.onEvent = onEvent || noop;
+        this.onError = onError || noop;
+        this.options = Object.assign(this.constructor.DEFAULT_OPTIONS, options);
+        this.id = uniqueId++;
+        ProvidersLogger.addEvent(this, 'constructor');
+    }
+
+    /**
+     * Get the provider name
+     * @public
+     * @abstract
+     */
+    static get displayName() {
+        return this.constructor.DEFAULT_NAME;
+    }
+
+    /**
+     * Get the list of events type which can be returned by the provider
+     * @returns {EventType[]} the list of events type
+     * @public
+     * @abstract
+     */
+    static get eventsType() {
+        return [];
+    }
+
+    /**
+     * @override
+     */
+    static checkAvailabilityErrors() {
+        return this.requiredProviders.reduce(
+            (acc, val) => acc.concat(val.checkAvailabilityErrors()), []
+        );
+    }
+
+    /**
+     * Return the list of required providers
+     */
+    static get requiredProviders() {
+        return [];
+    }
+
+    /**
+     * Start the Provider
+     * @public
+     */
+    start() {
+        if (this.state === Provider.State.STARTING
+            || this.state === Provider.State.STARTED) {
+            Logger.warn(Provider.Warnings.ALREADY_STARTED);
+            return;
+        }
+        this.state = Provider.State.STARTING;
+
+        if (this.options.checkAvailabilityOnStart) {
+            const availabilityErrors = this.constructor.checkAvailabilityErrors();
+            if (availabilityErrors.length !== 0) {
+                this.notifyError(...availabilityErrors);
+                return;
+            }
+        }
+
+        ProvidersLogger.addEvent(this, 'start');
+        this.state = Provider.State.STARTED;
+        this.startInternal();
+    }
+
+    /**
+     * @abstract
+     */
+    startInternal() {
+        throw new Error('Provider "' + this.constructor.name
+            + '" does not @override startInternal()');
+    }
+
+    /**
+     * Stop the Provider
+     * @public
+     */
+    stop() {
+
+        if (this.state === Provider.State.STOPPPED) {
+            Logger.warn(Provider.Warnings.ALREADY_STOPPED);
+            return;
+        }
+
+        ProvidersLogger.addEvent(this, 'stop');
+        this.state = Provider.State.STOPPPED;
+        this.stopInternal();
+    }
+
+    /**
+     * @abstract
+     */
+    stopInternal() {
+        throw new Error('Provider "' + this.constructor.name
+            + '" does not @override stopInternal()');
+    }
+
+
+    /**
+     * Notify the subscriber defined in {@link constructor}
+     * @param {ProviderEvent[]} events events to send to subscriber
+     */
+    notify(...events) {
+        ProvidersLogger.incrementNotifications(this);
+        this.onEvent(events);
+    }
+
+    /**
+     * Notify the subscriber defined in {@link constructor}
+     * @param {ProviderError[]} errors The error raised
+     */
+    notifyError(...errors) {
+        this.onError(errors);
+        if (this.options.stopOnError && this.state === Provider.State.STARTED) {
+            this.stop();
+        }
+    }
+
+    /**
+     * Create an event from current provider
+     * @param {ProviderEvent#DataType} dataType type of ProviderEvent
+     * @param {Object} data data exported to ProviderEvent
+     * @param {Number} timestamp event timestamp
+     * @protected
+     */
+    static createEvent(dataType, data, timestamp) {
+        const event = new ProviderEvent(this.constructor.name, dataType, data);
+        if (timestamp) {
+            event.timestamp = timestamp;
+        }
+        return event;
+    }
+
+    /**
+     * Create an event from current provider
+     * @param {EventType} dataType type of ProviderEvent
+     * @param {Object} data data exported to ProviderEvent
+     * @param {Number} timestamp event timestamp
+     * @protected
+     */
+    createEvent(dataType, data, timestamp) {
+        return this.constructor.createEvent(dataType, data, timestamp);
+    }
+
+    /**
+     * Create an event error from current provider
+     * @param {EventType} dataType type of ProviderError
+     * @param {ProviderError} error error raised by the problem exported to ProviderError
+     * @param {Number} timestamp event timestamp
+     * @protected
+     */
+    static createError(dataType, error, timestamp) {
+        const event = new ProviderError(this.name, dataType, error);
+        if (timestamp) {
+            event.timestamp = timestamp;
+        }
+        return event;
+    }
+
+    /**
+     * Create an event error from current provider
+     * @param {EventType} dataType type of ProviderError
+     * @param {ProviderError} error error raised by the problem exported to ProviderError
+     * @param {Number} timestamp event timestamp
+     * @protected
+     */
+    createError(dataType, error, timestamp) {
+        return this.constructor.createError(dataType, error, timestamp);
+    }
+
+
+    static hasNativeInterface() {
+        return Boolean(Provider.getNativeInterface());
+    }
+
+    static getNativeInterface() {
+        return global.WemapProvidersAndroid;
+    }
+
+    static createMissingNativeInterfaceError(dataType) {
+        return this.createError(dataType, new MissingNativeInterfaceError());
+    }
+}
+
+export default Provider;

package/src/providers/ProviderOptions.js

@@ -0,0 +1,28 @@
+const ProviderOptions = {
+
+    /**
+     * Does provider have to wait an input position to start
+     * @see PositioningHandler#setLocation()
+     */
+    waitInputPosition: false,
+
+    /**
+     * Does provider have to wait an input heading to start
+     * @see PositioningHandler#setHeading()
+     */
+    waitInputHeading: false,
+
+    /**
+     * Does provider will use map to
+     * @see PositioningHandler#setItinerary()
+     */
+    useMapMatching: false,
+
+    /**
+     * Providers listed here will not be used by PositioningHandler
+     * List of {@link Provider}
+     */
+    ignoreProviders: []
+};
+
+export default ProviderOptions;

package/{src.old → src}/providers/ProvidersLogger.js

@@ -20,7 +20,7 @@ class ProvidersLogger {
         interval = setInterval(() => {
 
             for (const [key, value] of Object.entries(pushEvents)) {
-                Logger.debug('Received ' + value + ' values from ' + pushEventsRef[key].constructor.name + ' last second');
+                Logger.debug('Received ' + value + ' notifications from ' + pushEventsRef[key].constructor.name + ' last second');
             }
 
             pushEvents = {};
@@ -53,7 +53,7 @@ class ProvidersLogger {
         Logger.debug(objectClassName + '[' + objectId + '].' + method);
     }
 
-    static addPushEvent(object) {
+    static incrementNotifications(object) {
 
         if (!ProvidersLogger.enabled) {
             return;

package/src/providers/attitude/AbsoluteAttitudeProvider.js

@@ -0,0 +1,207 @@
+import geomagnetism from 'geomagnetism';
+
+import {
+    Attitude, WGS84
+} from '@wemap/geo';
+import {
+    deg2rad, rad2deg, Quaternion, Rotations
+} from '@wemap/maths';
+import {
+    Browser, BrowserUtils
+} from '@wemap/utils';
+
+import Provider from '../Provider';
+import EventType from '../../events/EventType';
+import AskImuOnDesktopError from '../../errors/AskImuOnDesktopError';
+import MissingMagnetometerError from '../../errors/MissingMagnetometerError';
+import MissingSensorError from '../../errors/MissingSensorError';
+import Logger from '@wemap/logger';
+
+
+/**
+ * Absolute attitude provider gives the device attitude in East-North-Up (ENU) frame using
+ *  browser deviceorientation or deviceorientationabsolute
+ * The provider does not work until an AbsolutePosition is given. This is necessary to
+ *  calculate declination.
+ *
+ * -----------------------------------
+ * Overview of compatibilities:
+ * -----------------------------------
+ *
+ * Chrome Android (v72.0.3626): YES (via deviceorientationabsolute)
+ * Safari iOS (v12.0): YES (via deviceorientation and event.webkitCompassHeading)
+ * Opera Android (v50.2.2426): NO {@link https://developer.mozilla.org/en-US/docs/Web/API/Window/ondeviceorientation}
+ * Firefox Android (v65.0.1): NO {@link https://www.fxsitecompat.com/en-CA/docs/2018/various-device-sensor-apis-are-now-deprecated/}
+ *
+ * -----------------------------------
+ */
+class AbsoluteAttitudeProvider extends Provider {
+
+    /**
+    * @override
+    */
+    static get displayName() {
+        return 'Absolute Attitude from Browser';
+    }
+
+    /**
+     * @override
+     */
+    static get eventsType() {
+        return [EventType.AbsoluteAttitude];
+    }
+
+    /**
+     * @override
+     */
+    static checkAvailabilityErrors() {
+
+        if (BrowserUtils.isMobile) {
+            return [];
+        }
+
+        return [
+            AbsoluteAttitudeProvider.createError(
+                EventType.AbsoluteAttitude,
+                new AskImuOnDesktopError()
+            )
+        ];
+    }
+
+    /**
+     * @override
+     */
+    startInternal() {
+        switch (BrowserUtils.name) {
+        case Browser.CHROME:
+            window.addEventListener('deviceorientationabsolute',
+                this.onDeviceOrientationChromeEvent, true);
+            break;
+
+        case Browser.SAFARI:
+            window.addEventListener('deviceorientation',
+                this.onDeviceOrientationSafariEvent, true);
+            break;
+        }
+    }
+
+    /**
+     * @override
+     */
+    stopInternal() {
+        switch (BrowserUtils.name) {
+        case Browser.CHROME:
+            window.removeEventListener('deviceorientationabsolute',
+                this.onDeviceOrientationChromeEvent, true);
+            break;
+
+        case Browser.SAFARI:
+            window.removeEventListener('deviceorientation',
+                this.onDeviceOrientationSafariEvent, true);
+            break;
+        }
+    }
+
+
+    onDeviceOrientationChromeEvent = e => {
+
+        const timestamp = e.timeStamp / 1e3;
+
+        if (!e.alpha || !e.beta || !e.gamma) {
+            super.notifyError(this.createError(
+                EventType.AbsoluteAttitude,
+                new MissingSensorError().from('deviceorientationabsolute'),
+                timestamp
+            ));
+            return;
+        }
+        this.onDeviceOrientationCommonEvent(timestamp,
+            Rotations.eulerToQuaternionZXYDegrees([e.alpha, e.beta, e.gamma]));
+    };
+
+
+    onDeviceOrientationSafariEvent = e => {
+
+        const timestamp = e.timeStamp / 1e3;
+
+        if (!e.beta || !e.gamma) {
+            super.notifyError(this.createError(
+                EventType.AbsoluteAttitude,
+                new MissingSensorError().from('deviceorientation'),
+                timestamp
+            ));
+            return;
+        }
+
+        if (!e.webkitCompassHeading) {
+            super.notifyError(this.createError(
+                EventType.AbsoluteAttitude,
+                new MissingMagnetometerError().from('deviceorientation'),
+                timestamp
+            ));
+            return;
+        }
+
+        let webkitCompassHeading = -e.webkitCompassHeading;
+        // Be Careful: webkitCompassHeading is not continuous.
+        // Reference frame changes in function of beta with thresholds: beta > 30deg and beta < 62deg
+        // Below 30deg, East-North-Up (ENU) frame is used
+        // Above 62def, East-Up-South (EUS) frame is used
+        // Between 30deg and 62deg either ENU or EUS can be used
+        if (e.beta > 62) {
+            webkitCompassHeading = AbsoluteAttitudeProvider.headingEusToEnu(
+                180 - webkitCompassHeading, e.beta, e.gamma);
+        }
+        const quaternion = Rotations.eulerToQuaternionZXYDegrees(
+            [webkitCompassHeading, e.beta, e.gamma]);
+
+        this.onDeviceOrientationCommonEvent(timestamp, quaternion);
+    };
+
+
+    onDeviceOrientationCommonEvent = (timestamp, quaternion) => {
+
+        if (!this.declinationQuaternion) {
+            Logger.warn('Location of AbsoluteAttitude provider is not set yet. '
+                + 'Please call setLocation() before.');
+            return;
+        }
+        const trueQuaternion = Quaternion.multiply(this.declinationQuaternion, quaternion);
+
+        super.notify(
+            this.createEvent(
+                EventType.AbsoluteAttitude,
+                new Attitude(trueQuaternion),
+                timestamp
+            )
+        );
+    }
+
+    /**
+     * Initialized declination quaternion using current location.
+     * This method should be theoretically called every time the user moves.
+     * But in reality declination does not change as much.
+     * @param {WGS84} location user location
+     */
+    setLocation(location) {
+        const wmmResult = geomagnetism.model().point([location.lat, location.lng]);
+        // Declination is given in NED frame and our code use ENU, that is why we have: "-decl"
+        this.declinationQuaternion = Quaternion.fromAxisAngle([0, 0, 1], - deg2rad(wmmResult.decl));
+    }
+
+    /**
+     * {@link https://math.stackexchange.com/questions/3181981/solve-a-system-of-rotation-matrices-z-x-z-z-x-y}
+     */
+    static headingEusToEnu(_alpha, _beta, _gamma) {
+        const alpha = deg2rad(_alpha);
+        const beta = deg2rad(_beta);
+        const gamma = deg2rad(_gamma);
+
+        return rad2deg(Math.atan2(
+            Math.cos(alpha) * Math.sin(gamma) + Math.cos(gamma) * Math.sin(alpha) * Math.sin(beta),
+            Math.sin(alpha) * Math.sin(gamma) - Math.cos(alpha) * Math.cos(gamma) * Math.sin(beta)
+        ));
+    }
+}
+
+export default AbsoluteAttitudeProvider;

package/src/providers/attitude/RelativeAttitudeProvider.js

@@ -0,0 +1,129 @@
+import Provider from '../Provider';
+import EventType from '../../events/EventType';
+import EkfAttitude from './EkfAttitude';
+import ImuProvider from '../others/ImuProvider';
+import { Attitude } from '@wemap/geo';
+import { deg2rad } from '@wemap/maths';
+import ProviderError from '../../events/ProviderError';
+
+
+/**
+ * Relative attitude provider gives the device attitude in East-North-Up (ENU) frame using
+ *  browser deviceorientation
+ * The provider does not work until an offset is given.
+ */
+class RelativeAttitudeProvider extends Provider {
+
+    lastTimestamp = 0;
+
+    /**
+     * @override
+     */
+    constructor(onEvent, onError, options) {
+        super(onEvent, onError, options);
+
+        this.ekfAttitude = new EkfAttitude();
+        this.relativeOffsetQuaternion = [1, 0, 0, 0];
+
+        this.imuProvider = new ImuProvider(this.onImuEvent,
+            this.onImuError, { require: [EventType.Acceleration, EventType.AngularRate] });
+
+    }
+
+    /**
+    * @override
+    */
+    static get displayName() {
+        return 'Relative Attitude from Ekf';
+    }
+
+    /**
+     * @override
+     */
+    static get eventsType() {
+        return [EventType.RelativeAttitude];
+    }
+
+    /**
+     * @override
+     */
+    static get requiredProviders() {
+        return [ImuProvider];
+    }
+
+    /**
+     * @override
+     */
+    startInternal() {
+        this.imuProvider.start();
+    }
+
+    /**
+     * @override
+     */
+    stopInternal() {
+        this.imuProvider.stop();
+    }
+
+    /**
+     * @private
+     */
+    onImuEvent = imuEvent => {
+
+        let timestamp, acceleration, angularRate;
+        imuEvent.forEach(event => {
+            if (event.dataType === EventType.Acceleration) {
+                acceleration = event.data;
+                timestamp = event.timestamp;
+            } else if (event.dataType === EventType.AngularRate) {
+                angularRate = event.data;
+            }
+        });
+
+        // Handle timestamps and dt
+        if (this.lastTimestamp === 0) {
+            this.lastTimestamp = timestamp;
+            return;
+        }
+        const diffTime = timestamp - this.lastTimestamp;
+        this.lastTimestamp = timestamp;
+
+        const quaternion = this.ekfAttitude.update(diffTime, acceleration, angularRate);
+
+        if (quaternion) {
+            this.notify(this.createEvent(EventType.RelativeAttitude, new Attitude(quaternion), timestamp));
+        }
+    };
+
+    /**
+     *
+     * Set yaw offset, this value will be used as the filter does not use magnetometer
+     * @param {Number} heading heading offset in radians and clockwise
+     */
+    setOffset(_heading) {
+
+        // Minus before "heading" is here because ENU attitude is counter-clockwise whereas WGS84 heading is clockwise.
+        let heading = -_heading;
+
+        // Offset from window orientation
+        heading += deg2rad(window.orientation || 0);
+
+        this.ekfAttitude.setOrientationYaw(heading);
+    }
+
+    onImuError = imuErrors => {
+        this.notifyError(...ProviderError.modifyArrayDataType(imuErrors, EventType.RelativeAttitude));
+    }
+
+    /**
+     * @override
+     */
+    static checkAvailabilityErrors() {
+        return ProviderError.modifyArrayDataType(
+            super.checkAvailabilityErrors(),
+            EventType.RelativeAttitude
+        );
+    }
+}
+
+export default RelativeAttitudeProvider;