@mappedin/blue-dot 6.15.0-beta.0 → 6.17.0-beta.0

package/lib/esm/react/index.d.ts

@@ -1,10 +1,7 @@
 import { Coordinate, Floor, MapView, Model } from "@mappedin/mappedin-js";
 
-//#region ../packages/common/browser.d.ts
-
-type BrowserPermissionState = PermissionState | 'unavailable';
-//#endregion
 //#region ../../node_modules/.pnpm/type-fest@5.4.2/node_modules/type-fest/source/primitive.d.ts
+
 /**
 Matches any [primitive value](https://developer.mozilla.org/en-US/docs/Glossary/Primitive).
 
@@ -872,25 +869,6 @@ Same as `ReadonlyDeep`, but accepts only `object`s as inputs. Internal helper fo
 */
 type _ReadonlyObjectDeep<ObjectType extends object> = { readonly [KeyType in keyof ObjectType]: ReadonlyDeep<ObjectType[KeyType]> };
 //#endregion
-//#region ../packages/common/extensions.d.ts
-interface MapViewExtension<T> {
-  enable(options?: PartialDeep<T>): void;
-  disable(): void;
-  get isEnabled(): boolean;
-  destroy(): void;
-}
-//#endregion
-//#region src/status/types.d.ts
-type BlueDotStatus = 'hidden' | 'active' | 'inactive' | 'disabled';
-type BlueDotAction = 'timeout' | 'error' | 'position-update' | 'enable' | 'disable' | 'initialize';
-//#endregion
-//#region src/follow/types.d.ts
-type FollowMode = /** Camera position follows the Blue Dot's position. */
-'position-only'
-/** Camera position follows the Blue Dot's position. Camera bearing matches the Blue Dot's heading. */ | 'position-and-heading'
-/** Camera position follows the Blue Dot's position. Camera bearing is calculated based on the Navigation path. */ | 'position-and-path-direction'
-/** Disables follow mode */ | false;
-//#endregion
 //#region src/sensors/types.d.ts
 /**
  * Built-in sensor IDs
@@ -1028,7 +1006,34 @@ type SensorEventPayloads = {
   };
 };
 //#endregion
+//#region src/fusion/anchor-state.d.ts
+/**
+ * Anchor state in the fusion engine's hybrid anchor behavior model.
+ *
+ * - `'none'`: No anchor active; GPS measurements accepted, PDR ignored
+ * - `'anchor-only'`: Anchor active and in exclusive period; GPS rejected, PDR accepted
+ * - `'transition'`: Anchor active but past exclusive period; GPS accepted with increasing weight
+ */
+type AnchorState = 'none' | 'anchor-only' | 'transition';
+//#endregion
 //#region src/fusion/types.d.ts
+type FusionEventPayloads = {
+  'fused-position': {
+    position: FusedPosition;
+  };
+  'heading-update': {
+    heading: number;
+  };
+  'anchor-set': {
+    anchor: PositionAnchor;
+  };
+  'anchor-expired': {
+    anchor: PositionAnchor;
+  };
+  error: {
+    error: Error | GeolocationPositionError;
+  };
+};
 type PositionMetadata = {
   /** Confidence score 0-1 (0 = no confidence, 1 = 100% certain) */
   confidence: number;
@@ -1109,6 +1114,29 @@ interface RelativePositionUpdate {
   /** Confidence score 0-1 */
   confidence: number;
 }
+/**
+ * Configuration for the multi-sensor EKF fusion engine.
+ */
+interface FusionEngineConfig {
+  /**
+   * Duration in ms where anchor is exclusive (GPS rejected).
+   * @default 5000 (5 seconds)
+   */
+  anchorOnlyPeriodMs: number;
+  /**
+   * Half-life for state uncertainty growth in milliseconds.
+   * The state uncertainty doubles every halfLifeMs when no measurements arrive.
+   * Lower values = faster decay of old position estimates.
+   * @default 10000 (10 seconds)
+   */
+  halfLifeMs: number;
+  /**
+   * Maximum age of position updates to consider in milliseconds.
+   * Updates older than this cause filter reset.
+   * @default 5000 (5 seconds)
+   */
+  maxAgeMs: number;
+}
 /**
  * Position anchor from a calibration source (VPS, AI Localizer).
  * Anchors represent absolute ground truth positions that other sensors
@@ -1137,6 +1165,28 @@ interface PositionAnchor {
   confidence?: number;
 }
 //#endregion
+//#region ../packages/common/browser.d.ts
+type BrowserPermissionState = PermissionState | 'unavailable';
+//#endregion
+//#region ../packages/common/extensions.d.ts
+interface MapViewExtension<T> {
+  enable(options?: PartialDeep<T>): void;
+  disable(): void;
+  get isEnabled(): boolean;
+  destroy(): void;
+}
+//#endregion
+//#region src/status/types.d.ts
+type BlueDotStatus = 'hidden' | 'active' | 'inactive' | 'disabled';
+type BlueDotAction = 'timeout' | 'error' | 'position-update' | 'enable' | 'disable' | 'initialize';
+//#endregion
+//#region src/follow/types.d.ts
+type FollowMode = /** Camera position follows the Blue Dot's position. */
+'position-only'
+/** Camera position follows the Blue Dot's position. Camera bearing matches the Blue Dot's heading. */ | 'position-and-heading'
+/** Camera position follows the Blue Dot's position. Camera bearing is calculated based on the Navigation path. */ | 'position-and-path-direction'
+/** Disables follow mode */ | false;
+//#endregion
 //#region src/types.d.ts
 type FollowCameraOptions = {
   /**
@@ -1922,6 +1972,329 @@ declare class SensorRegistry extends PubSub<SensorEventPayloads> {
   destroy(): void;
 }
 //#endregion
+//#region src/fusion/algorithms/types.d.ts
+/**
+ * Interface for heading fusion algorithms.
+ * Combines compass, gyroscope, and GPS heading for stable heading estimation.
+ */
+interface HeadingFusionAlgorithm {
+  /**
+   * Update with compass heading (absolute but noisy).
+   * @param heading Compass heading in degrees [0, 360)
+   * @param timestamp Update timestamp in milliseconds
+   */
+  updateCompass(heading: number, timestamp: number): void;
+  /**
+   * Update with gyroscope angular velocity (smooth relative changes).
+   * @param angularVelocity Angular velocity in deg/s around vertical axis
+   * @param timestamp Update timestamp in milliseconds
+   */
+  updateGyro(angularVelocity: number, timestamp: number): void;
+  /**
+   * Correct heading with GPS ground truth when moving.
+   * @param gpsHeading GPS heading in degrees [0, 360)
+   * @param speed Current speed in m/s
+   */
+  correctWithGps(gpsHeading: number, speed: number): void;
+  /**
+   * Get the current fused heading.
+   * @returns Fused heading in degrees [0, 360), or null if not initialized
+   */
+  getHeading(): number | null;
+  /**
+   * Reset the algorithm state.
+   */
+  reset(): void;
+}
+//#endregion
+//#region src/fusion/algorithms/heading-filter.d.ts
+/**
+ * Configuration options for the heading fusion filter.
+ */
+interface HeadingFilterConfig {
+  /** Complementary filter alpha (0-1). Higher = more gyro weight. */
+  complementaryAlpha: number;
+  /** Minimum angular velocity to integrate (deg/s). */
+  gyroNoiseThreshold: number;
+  /** Maximum heading error before snapping to compass (degrees). */
+  maxHeadingError: number;
+  /** Enable magnetic disturbance detection. */
+  magneticGatingEnabled: boolean;
+  /** Minimum heading delta to emit updates (degrees). */
+  deltaThreshold: number;
+}
+/**
+ * Complementary filter for heading fusion.
+ * Combines compass (absolute but noisy), gyroscope (smooth relative changes),
+ * and GPS heading (ground truth when moving) to produce stable heading.
+ *
+ * The filter works by:
+ * 1. Short-term: Integrate gyroscope angular velocity for smooth rotations
+ * 2. Long-term: Slowly blend toward compass to prevent gyroscope drift
+ * 3. Correction: When GPS heading is valid (moving fast enough), use as ground truth
+ *
+ * @example
+ * ```ts
+ * const filter = new HeadingFusionFilter();
+ *
+ * // Update with compass reading
+ * filter.updateCompass(45, Date.now());
+ *
+ * // Update with gyroscope angular velocity
+ * filter.updateGyro(5.0, Date.now()); // 5 deg/s rotation
+ *
+ * // Correct with GPS when moving
+ * filter.correctWithGps(47, 1.5); // heading 47°, speed 1.5 m/s
+ *
+ * // Get fused heading
+ * const heading = filter.getHeading(); // ~46°
+ * ```
+ */
+declare class HeadingFusionFilter implements HeadingFusionAlgorithm {
+  #private;
+  /**
+   * Update the filter with a compass heading reading.
+   * The compass provides absolute heading but is susceptible to magnetic interference.
+   * @param heading Compass heading in degrees [0, 360)
+   * @param timestamp Update timestamp in milliseconds
+   */
+  updateCompass(heading: number, _timestamp: number): void;
+  /**
+   * Update the filter with gyroscope angular velocity.
+   * The gyroscope provides smooth relative heading changes immune to magnetic fields.
+   * @param angularVelocity Angular velocity around vertical axis in deg/s
+   * @param timestamp Update timestamp in milliseconds
+   */
+  updateGyro(angularVelocity: number, timestamp: number): void;
+  /**
+   * Correct the heading with GPS when available.
+   * GPS heading is only considered when moving fast enough and with sufficient confidence.
+   * @param gpsHeading GPS heading in degrees [0, 360)
+   * @param speed Current speed in m/s
+   * @param confidence GPS confidence (0-1), affects how much GPS heading influences result
+   */
+  correctWithGps(gpsHeading: number, speed: number, confidence?: number): void;
+  /**
+   * Configure the filter parameters at runtime.
+   * @param config Partial configuration to apply
+   */
+  configure(config: Partial<HeadingFilterConfig>): void;
+  /**
+   * Get current configuration values.
+   */
+  getConfig(): HeadingFilterConfig;
+  /**
+   * Check if magnetic disturbance is currently detected.
+   */
+  isMagneticDisturbanceActive(): boolean;
+  /**
+   * Get the current fused heading.
+   * @returns Fused heading in degrees [0, 360), or null if not initialized
+   */
+  getHeading(): number | null;
+  /**
+   * Check if the filter has been initialized with at least one compass reading.
+   * @returns True if filter is initialized
+   */
+  isInitialized(): boolean;
+  /**
+   * Get the last compass heading received.
+   * @returns Last compass heading in degrees, or null if none received
+   */
+  getLastCompassHeading(): number | null;
+  /**
+   * Reset the filter state.
+   * Call on floor changes or when heading should be re-initialized.
+   */
+  reset(): void;
+}
+//#endregion
+//#region src/fusion/algorithms/multi-sensor-ekf.d.ts
+/**
+ * Configuration options for the Multi-Sensor EKF.
+ */
+interface MultiSensorEKFOptions {
+  /**
+   * Half-life for uncertainty growth in milliseconds.
+   * The state uncertainty doubles every halfLifeMs when no measurements arrive.
+   * Lower values = faster decay of old estimates.
+   * @default 10000 (10 seconds)
+   */
+  halfLifeMs: number;
+}
+/**
+ * Multi-sensor Extended Kalman Filter for position fusion.
+ *
+ * Combines position measurements from multiple sources (GPS, VPS, anchors) and
+ * displacement measurements from PDR using a constant-velocity motion model.
+ *
+ * Key features:
+ * - All methods take explicit timestamps (no Date.now() inside)
+ * - Confidence-weighted fusion via measurement noise parameter
+ * - Half-life decay of old estimates via process noise scaling
+ * - Supports both absolute position and relative displacement updates
+ *
+ * State vector: [latitude, longitude, velocity_lat, velocity_lon]
+ *
+ * @example
+ * ```ts
+ * const ekf = new MultiSensorEKF({ halfLifeMs: 10000 });
+ *
+ * // Initialize with first position
+ * ekf.updatePosition(43.123, -79.456, 0.0001, 0);
+ *
+ * // Predict forward
+ * ekf.predict(1000);
+ *
+ * // Update with new GPS measurement (low confidence = high noise)
+ * ekf.updatePosition(43.124, -79.455, 0.001, 1000);
+ *
+ * // Get fused position
+ * const pos = ekf.getPosition(); // { latitude: ~43.1235, longitude: ~-79.4555 }
+ * ```
+ */
+declare class MultiSensorEKF {
+  #private;
+  constructor(options?: Partial<MultiSensorEKFOptions>);
+  /**
+   * Predict step: project state forward to the given timestamp.
+   * Increases uncertainty based on elapsed time and half-life configuration.
+   *
+   * @param timestampMs - Current timestamp in milliseconds
+   */
+  predict(timestampMs: number): void;
+  /**
+   * Update state with a position measurement (GPS, VPS, anchor).
+   *
+   * @param latitude - Measured latitude in degrees
+   * @param longitude - Measured longitude in degrees
+   * @param measurementNoise - Measurement noise variance (higher = less trust)
+   * @param timestampMs - Measurement timestamp in milliseconds
+   */
+  updatePosition(latitude: number, longitude: number, measurementNoise: number, timestampMs: number): void;
+  /**
+   * Update state with an odometry measurement (PDR displacement).
+   *
+   * Unlike position updates, odometry provides relative displacement rather than
+   * absolute position. The displacement is added directly to the state.
+   *
+   * @param dx - Displacement east in meters (positive = east)
+   * @param dy - Displacement north in meters (positive = north)
+   * @param measurementNoise - Measurement noise variance (higher = less trust)
+   * @param timestampMs - Measurement timestamp in milliseconds
+   */
+  updateOdometry(dx: number, dy: number, measurementNoise: number, timestampMs: number): void;
+  /**
+   * Get the current position estimate.
+   * @returns Position or null if filter not initialized
+   */
+  getPosition(): {
+    latitude: number;
+    longitude: number;
+  } | null;
+  /**
+   * Get the current velocity estimate.
+   * @returns Velocity in degrees per second, or null if filter not initialized
+   */
+  getVelocity(): {
+    vLat: number;
+    vLon: number;
+  } | null;
+  /**
+   * Get the current position uncertainty (trace of position covariance).
+   * Higher values indicate less certainty in the position estimate.
+   * @returns Uncertainty value, or Infinity if filter not initialized
+   */
+  getUncertainty(): number;
+  /**
+   * Get the last update timestamp.
+   * @returns Timestamp in ms, or null if filter not initialized
+   */
+  getLastTimestamp(): number | null;
+  /**
+   * Check if the filter has been initialized with at least one measurement.
+   */
+  isInitialized(): boolean;
+  /**
+   * Reset the filter state.
+   * Call on floor changes, large position jumps, or time gaps.
+   */
+  reset(): void;
+}
+//#endregion
+//#region src/fusion/fusion-engine.d.ts
+/**
+ * Multi-sensor fusion engine that combines position updates from multiple sources.
+ *
+ * Uses an Extended Kalman Filter (EKF) for position fusion with:
+ * - Confidence-weighted measurements (high confidence = more influence)
+ * - Half-life decay of old estimates (uncertainty grows over time)
+ * - Hybrid anchor behavior (anchor-only period, then transition to GPS)
+ *
+ * Heading fusion uses a separate complementary filter combining compass and gyroscope.
+ */
+declare class FusionEngine extends PubSub<FusionEventPayloads> {
+  #private;
+  constructor(registry: SensorRegistry, config?: Partial<FusionEngineConfig>);
+  /**
+   * Get the current fusion configuration.
+   */
+  get config(): Readonly<FusionEngineConfig>;
+  /**
+   * Get the current anchor state.
+   * @param nowMs - Current timestamp (defaults to Date.now())
+   */
+  getAnchorState(nowMs?: number): AnchorState;
+  /**
+   * Get the current position anchor if one is set and not expired.
+   */
+  get anchor(): Readonly<PositionAnchor> | undefined;
+  /**
+   * Get the current accumulated displacement from the anchor in meters.
+   * Returns (0, 0) if no anchor is set or no movement has occurred.
+   */
+  get displacement(): Readonly<DisplacementVector>;
+  /**
+   * Set an absolute position anchor from a calibration source (VPS, AI Localizer).
+   * When an anchor is active, it provides the absolute position and other sensors
+   * can provide relative updates from this reference point.
+   *
+   * @param anchor - The position anchor to set
+   * @param configOverride - Optional config overrides for this anchor (e.g., anchorOnlyPeriodMs)
+   */
+  setAnchor(anchor: PositionAnchor, configOverride?: Partial<Pick<FusionEngineConfig, 'anchorOnlyPeriodMs'>>): void;
+  /**
+   * Clear the current position anchor and accumulated displacement.
+   */
+  clearAnchor(): void;
+  /**
+   * Reset the EKF state.
+   * Call on floor changes or large position jumps.
+   */
+  resetEKF(): void;
+  /**
+   * Reset the heading fusion filter state.
+   * Call on floor changes or when heading should be re-initialized.
+   */
+  resetHeadingFilter(): void;
+  /**
+   * Get the heading fusion filter for configuration.
+   * @internal Used by debug tools for runtime tuning.
+   */
+  get headingFilter(): HeadingFusionFilter;
+  /**
+   * Get the multi-sensor EKF for inspection.
+   * @internal Used by debug tools for runtime inspection.
+   */
+  get ekf(): MultiSensorEKF;
+  /**
+   * Get the last fused position.
+   * @returns The last fused position, or undefined if none available
+   */
+  getLastPosition(): FusedPosition | undefined;
+  destroy(): void;
+}
+//#endregion
 //#region src/blue-dot.d.ts
 /**
  * Show a Blue Dot indicating the device's position on the map.
@@ -1954,6 +2327,21 @@ declare class BlueDot implements MapViewExtension<BlueDotState> {
   constructor(mapView: MapView);
   /** Sensors API */
   get Sensors(): SensorRegistry;
+  /**
+   * Fusion engine API.
+   * @internal Used by debug tools for runtime tuning and inspection.
+   */
+  get Fusion(): FusionEngine;
+  /**
+   * Get the current position anchor if one is set and not expired.
+   * Anchors provide absolute ground truth positions from calibration sources (VPS, AI Localizer).
+   */
+  get anchor(): Readonly<PositionAnchor> | undefined;
+  /**
+   * Get the current accumulated displacement from the anchor in meters.
+   * Returns { dx: 0, dy: 0 } if no anchor is set or no movement has occurred.
+   */
+  get displacement(): Readonly<DisplacementVector>;
   /**
    * Get the Model for the BlueDot core element.
    */

package/lib/esm/react/index.js

@@ -1 +1 @@
-import{a as n,b as u,f}from"../chunk-O22D2X2S.js";u();u();import{useCallback as c,useState as p}from"react";import{useMap as D,useMapViewExtension as m}from"@mappedin/react-sdk";function B(){let[,t]=p({});return c(()=>t({}),[])}n(B,"useForceUpdate");function l(){let{mapView:t}=D(),o=B(),{register:r}=m("blue-dot",{onRegister:n(()=>{let e=new f(t);return e.on("position-update",o),e.on("status-change",o),e.on("follow-change",o),e.on("error",o),e},"onRegister"),onDeregister:n(e=>{e.off("position-update",o),e.off("status-change",o),e.off("follow-change",o),e.off("error",o),e.destroy()},"onDeregister")}),s=r();if(!s)throw new Error("BlueDot failed to initialize.");return s}n(l,"useBlueDot");u();import{useCallback as d,useEffect as E,useRef as g}from"react";function w(t,o){let r=l(),s=g(o);s.current=o;let e=d(i=>{s.current(i)},[]);E(()=>{if(r!=null)return r.on(t,e),()=>{r!=null&&r.off(t,e)}},[r,t,e])}n(w,"useBlueDotEvent");export{l as useBlueDot,w as useBlueDotEvent};
+import{d as f}from"../chunk-BRRC7V4T.js";import{c as n,m as u}from"../chunk-UVQMTLHL.js";u();u();import{useCallback as c,useState as p}from"react";import{useMap as D,useMapViewExtension as m}from"@mappedin/react-sdk";function B(){let[,t]=p({});return c(()=>t({}),[])}n(B,"useForceUpdate");function l(){let{mapView:t}=D(),o=B(),{register:r}=m("blue-dot",{onRegister:n(()=>{let e=new f(t);return e.on("position-update",o),e.on("status-change",o),e.on("follow-change",o),e.on("error",o),e},"onRegister"),onDeregister:n(e=>{e.off("position-update",o),e.off("status-change",o),e.off("follow-change",o),e.off("error",o),e.destroy()},"onDeregister")}),s=r();if(!s)throw new Error("BlueDot failed to initialize.");return s}n(l,"useBlueDot");u();import{useCallback as d,useEffect as E,useRef as g}from"react";function w(t,o){let r=l(),s=g(o);s.current=o;let e=d(i=>{s.current(i)},[]);E(()=>{if(r!=null)return r.on(t,e),()=>{r!=null&&r.off(t,e)}},[r,t,e])}n(w,"useBlueDotEvent");export{l as useBlueDot,w as useBlueDotEvent};

package/lib/rn/blue-dot.d.ts

@@ -7,6 +7,7 @@ import type { ReadonlyDeep } from 'type-fest';
 import { FollowMode } from './follow/types';
 import { BlueDotStatus } from './status/types';
 import { SensorRegistry } from './sensors/sensor-registry';
+import { FusionEngine } from './fusion/fusion-engine';
 import type { ManualPositionOptions } from './sensors/manual/manual-sensor';
 /**
  * Show a Blue Dot indicating the device's position on the map.
@@ -39,6 +40,21 @@ export declare class BlueDot implements MapViewExtension<BlueDotState> {
     constructor(mapView: MapView);
     /** Sensors API */
     get Sensors(): SensorRegistry;
+    /**
+     * Fusion engine API.
+     * @internal Used by debug tools for runtime tuning and inspection.
+     */
+    get Fusion(): FusionEngine;
+    /**
+     * Get the current position anchor if one is set and not expired.
+     * Anchors provide absolute ground truth positions from calibration sources (VPS, AI Localizer).
+     */
+    get anchor(): Readonly<import('./fusion/types').PositionAnchor> | undefined;
+    /**
+     * Get the current accumulated displacement from the anchor in meters.
+     * Returns { dx: 0, dy: 0 } if no anchor is set or no movement has occurred.
+     */
+    get displacement(): Readonly<import('./fusion/types').DisplacementVector>;
     /**
      * Get the Model for the BlueDot core element.
      */