quick GPS smoothing algorithm to handle wackiness on BASE terrace

Author: hburgund

src/geo-position.ts

@@ -1,8 +1,10 @@
+import { GeoEmaSmoother } from "./geo_smoothing";
 import { GeoListenMode } from "./mixer";
 import { logger } from "./shims";
 import { Coordinates, GeoPositionOptions } from "./types";
 
 const initialGeoTimeoutSeconds = 6;
+// default; can be overridden by options on Roundware instantiation
 const geoUpdateThrottleMs = 0;
 
 const frameworkDefaultCoords: Coordinates = {
@@ -44,6 +46,7 @@ export class GeoPosition {
   updateCallback: CallableFunction;
   private _geoWatchID?: number | null;
   private _geoPositionStatus: true | number = 3;
+  private _smoother?: GeoEmaSmoother;
 
   constructor(navigator: Window[`navigator`], options: GeoPositionOptions) {
     this._navigator = navigator;
@@ -63,6 +66,24 @@ export class GeoPosition {
     this.updateCallback = () => {};
     this._geoWatchID = null;
 
+    // Setup optional smoother
+    const {
+      geoSmoothingEnabled = false,
+      geoSmoothingAlpha = 0.15,
+      geoSmoothingMinAccuracyMeters = 20,
+      geoSmoothingMinEmitDeltaMeters = 0,
+      geoSmoothingResetJumpMeters = 50,
+    } = options;
+    if (geoSmoothingEnabled) {
+      this._smoother = new GeoEmaSmoother({
+        enabled: geoSmoothingEnabled,
+        alpha: geoSmoothingAlpha,
+        minAccuracyMeters: geoSmoothingMinAccuracyMeters,
+        minEmitDeltaMeters: geoSmoothingMinEmitDeltaMeters,
+        resetJumpMeters: geoSmoothingResetJumpMeters,
+      });
+    }
+
     //console.info({ defaultCoords: this.defaultCoords });
   }
 
@@ -174,11 +195,29 @@ export class GeoPosition {
           )}`
         );
 
+        // Optionally smooth before forwarding; always emit as simple Coordinates
+        let coordsToSend: Coordinates = {
+          latitude: coords.latitude,
+          longitude: coords.longitude,
+        };
+        if (this._smoother) {
+          const smoothed = this._smoother.update(updatedPosition);
+          if (smoothed) {
+            coordsToSend = {
+              latitude: smoothed.latitude,
+              longitude: smoothed.longitude,
+            };
+          } else {
+            // rejected by smoothing (poor accuracy or within deadband)
+            return;
+          }
+        }
+
         this._lastUpdateTime = now;
-        this._lastCoords = coords;
+        this._lastCoords = coordsToSend;
         this._geoPositionStatus = true;
-        logger.info("Received updated geolocation:", coords);
-        this.updateCallback(coords);
+        logger.info("Received updated geolocation:", coordsToSend);
+        this.updateCallback(coordsToSend);
       },
       (error) => {
         logger.warn(

src/geo_smoothing.ts

@@ -0,0 +1,82 @@
+import { Coordinates } from "./types";
+
+export type GeoSmoothingConfig = {
+  enabled: boolean;
+  alpha: number; // 0..1
+  minAccuracyMeters: number; // discard poor readings
+  minEmitDeltaMeters: number; // deadband; 0 disables
+  resetJumpMeters: number; // reset EMA if jump exceeds
+};
+
+function haversineMeters(a: Coordinates, b: Coordinates): number {
+  const R = 6371000; // meters
+  const lat1 = ((a.latitude || 0) * Math.PI) / 180;
+  const lat2 = ((b.latitude || 0) * Math.PI) / 180;
+  const dLat = (((b.latitude || 0) - (a.latitude || 0)) * Math.PI) / 180;
+  const dLon = (((b.longitude || 0) - (a.longitude || 0)) * Math.PI) / 180;
+  const s =
+    Math.sin(dLat / 2) ** 2 +
+    Math.cos(lat1) * Math.cos(lat2) * Math.sin(dLon / 2) ** 2;
+  const c = 2 * Math.atan2(Math.sqrt(s), Math.sqrt(1 - s));
+  return R * c;
+}
+
+export class GeoEmaSmoother {
+  private config: GeoSmoothingConfig;
+  private smoothed: Coordinates | null = null;
+
+  constructor(config: GeoSmoothingConfig) {
+    this.config = config;
+  }
+
+  reset(): void {
+    this.smoothed = null;
+  }
+
+  update(position: GeolocationPosition): Coordinates | null {
+    if (!this.config.enabled) return position.coords;
+
+    const { accuracy, latitude, longitude } = position.coords;
+    if (
+      typeof accuracy === "number" &&
+      accuracy > this.config.minAccuracyMeters
+    ) {
+      return null; // reject poor reading
+    }
+
+    const incoming: Coordinates = { latitude, longitude };
+
+    if (!this.smoothed) {
+      this.smoothed = incoming;
+      return this.smoothed;
+    }
+
+    // reset on teleport
+    if (
+      haversineMeters(this.smoothed, incoming) > this.config.resetJumpMeters
+    ) {
+      this.smoothed = incoming;
+      return this.smoothed;
+    }
+
+    const a = this.config.alpha;
+    this.smoothed = {
+      latitude:
+        a * (incoming.latitude || 0) + (1 - a) * (this.smoothed.latitude || 0),
+      longitude:
+        a * (incoming.longitude || 0) +
+        (1 - a) * (this.smoothed.longitude || 0),
+    };
+
+    if (this.config.minEmitDeltaMeters > 0) {
+      const delta = haversineMeters(this.smoothed, incoming);
+      if (delta < this.config.minEmitDeltaMeters) {
+        // hold last output; pretend no update
+        return null;
+      }
+    }
+
+    return this.smoothed;
+  }
+}
+

src/roundware.ts

@@ -24,24 +24,23 @@ import {
   Coordinates,
   GeoListenModeType,
   IAudioData,
-  IInitialParams,
   IMixParams,
   ITimedAssetData,
   IUiConfig,
 } from "./types";
-import { IAssetFilters } from "./types/asset";
-import { IAssetData } from "./types/asset";
+import { IAssetData, IAssetFilters } from "./types/asset";
 import { IAudioTrackData } from "./types/audioTrack";
 import { IEnvelopeData } from "./types/envelope";
 import { IOptions, IRoundwareConstructorOptions } from "./types/roundware";
 import { ISpeakerData, ISpeakerFilters } from "./types/speaker";
 import { User } from "./user";
 
 export * from "./assetFilters";
+export { GeoListenMode, Roundware };
 
-import { multiPolygon, featureCollection } from "@turf/helpers";
 import bbox from "@turf/bbox";
 import buffer from "@turf/buffer";
+import { featureCollection, multiPolygon } from "@turf/helpers";
 import { ListenHistory } from "./listenHistory";
 
 /** This class is the primary integration point between Roundware's server and your application
@@ -197,6 +196,13 @@ class Roundware {
       new GeoPosition(navigator, {
         geoListenMode: newOptions.geoListenMode,
         defaultCoords: listenerLocation,
+        geoSmoothingEnabled: newOptions.geoSmoothingEnabled,
+        geoSmoothingAlpha: newOptions.geoSmoothingAlpha,
+        geoSmoothingMinAccuracyMeters: newOptions.geoSmoothingMinAccuracyMeters,
+        geoSmoothingMinEmitDeltaMeters:
+          newOptions.geoSmoothingMinEmitDeltaMeters,
+        geoSmoothingResetJumpMeters: newOptions.geoSmoothingResetJumpMeters,
+        geoUpdateThrottleMs: newOptions.geoUpdateThrottleMs,
       });
     this._session =
       session ||
@@ -636,4 +642,3 @@ class Roundware {
     };
   }
 }
-export { GeoListenMode, Roundware };

src/types/index.ts

@@ -81,6 +81,12 @@ export interface IAudioData extends Blob {
 export interface GeoPositionOptions {
   defaultCoords: Coordinates;
   geoListenMode: GeoListenModeType;
+  geoSmoothingEnabled?: boolean;
+  geoSmoothingAlpha?: number;
+  geoSmoothingMinAccuracyMeters?: number;
+  geoSmoothingMinEmitDeltaMeters?: number;
+  geoSmoothingResetJumpMeters?: number;
+  geoUpdateThrottleMs?: number;
 }
 
 export interface IGeoPosition {

src/types/roundware.ts

@@ -17,6 +17,18 @@ export interface IOptions {
   deviceId: string;
   clientType?: string;
   geoListenMode: GeoListenModeType;
+  /** Enable EMA-based geo smoothing (default: false) */
+  geoSmoothingEnabled?: boolean;
+  /** EMA alpha in [0,1], lower = more smoothing (default: 0.15) */
+  geoSmoothingAlpha?: number;
+  /** Discard updates with accuracy worse than this (meters). Default: 20 */
+  geoSmoothingMinAccuracyMeters?: number;
+  /** Minimum movement before emitting new point (meters). Default: 0 (disabled) */
+  geoSmoothingMinEmitDeltaMeters?: number;
+  /** Reset EMA if jump exceeds this (meters). Default: 50 */
+  geoSmoothingResetJumpMeters?: number;
+  /** Throttle geolocation update handling (ms). Default: 0 (no throttle) */
+  geoUpdateThrottleMs?: number;
 }
 export interface IRoundwareConstructorOptions extends IOptions {
   serverUrl: string;
@@ -91,4 +103,12 @@ export type SpeakerConfig = {
   // newly submitted speaker priority configuration
   prioritizeNewlySubmitted?: boolean; // default: true - whether to prioritize newly submitted speakers
   newlySubmittedPriorityDurationMs?: number; // default: 30000 (30 seconds) - how long to prioritize newly submitted speakers
+
+  // GPS smoothing configuration
+  geoSmoothingEnabled?: boolean; // Enable EMA-based geo smoothing (default: false)
+  geoSmoothingAlpha?: number; // EMA alpha in [0,1], lower = more smoothing (default: 0.15)
+  geoSmoothingMinAccuracyMeters?: number; // Discard updates with accuracy worse than this (meters). Default: 20
+  geoSmoothingMinEmitDeltaMeters?: number; // Minimum movement before emitting new point (meters). Default: 0 (disabled)
+  geoSmoothingResetJumpMeters?: number; // Reset EMA if jump exceeds this (meters). Default: 50
+  geoUpdateThrottleMs?: number; // Throttle geolocation update handling (ms). Default: 0 (no throttle)
 };