gps-plus-slam-js

TypeScript library for real-time GPS + AR odometry alignment.

Proprietary — the full End User License Agreement is bundled inside the package as EULA.md. To read it before installing, open the package contents on npm and select EULA.md. After npm install gps-plus-slam-js, the same file is available at node_modules/gps-plus-slam-js/EULA.md. Use of this package requires a valid license key — a community key is bundled with the open-source companion packages, see License Key below.

gps-plus-slam-js fuses AR pose tracking (odometry) with GPS readings to compute a transformation matrix that maps device-local coordinates to geo-referenced positions. It is designed for location-based AR applications where accurate outdoor positioning matters.

• Sub-meter positioning — Combines high-frequency AR odometry with noisy GPS to produce smoother, more accurate trajectories than raw GPS alone.
• Fully offline — All computation runs on-device with no network requests; works in airplane mode or areas without connectivity.
• Framework-agnostic — Pure TypeScript with a Redux-based state store; integrates with any AR runtime (WebXR, AR Foundation, etc.).
• Incremental alignment — The alignment matrix updates live as new observations arrive; no batch post-processing required.

Installation

npm install gps-plus-slam-js

Requires Node.js ≥ 20.

Quick Start

import {
  createGpsSlamStore,
  setZeroPos,
  recordGpsEvent,
  getAlignmentMatrix,
  getZeroReference,
  fusedGpsFromOdom,
} from 'gps-plus-slam-js';

// 1. Create the state store
const store = createGpsSlamStore();

// 2. Set the GPS origin (zero reference)
store.dispatch(setZeroPos({ lat: 48.2082, lon: 16.3738 }));

// 3. Feed odometry + GPS observations
store.dispatch(
  recordGpsEvent({
    odomPosition: [x, y, z], // AR-local position
    odomRotation: [qx, qy, qz, qw], // AR-local rotation
    gpsPoint: {
      id: crypto.randomUUID(),
      zeroRef: { lat: 48.2082, lon: 16.3738 },
      latitude: 48.2083,
      longitude: 16.3739,
      altitude: 170,
      latLongAccuracy: 5,
      coordinates: [dx, dy, dz], // meters relative to zeroRef
      weight: 1,
      timestamp: Date.now(),
    },
  })
);

// 4. Read the computed alignment
const state = store.getState();
const matrix = getAlignmentMatrix(state); // 4×4 column-major Matrix4 | null
const zeroRef = getZeroReference(state); // { lat, lon } | null

// 5. Convert any AR position to GPS coordinates
if (matrix && zeroRef) {
  const gps = fusedGpsFromOdom(matrix, [x, y, z], zeroRef);
  console.log(gps.lat, gps.lon, gps.altitude);
}

API Overview

Store

| Export | Description | | ------------------------------ | --------------------------------------- | | createGpsSlamStore(options?) | Create a Redux store for GPS+SLAM state | | LIB_VERSION | Library version string |

Actions (dispatch to the store)

| Export | Description | | --------------------------------------------------------- | ------------------------------------ | | setZeroPos({ lat, lon }) | Set the GPS origin | | recordGpsEvent(payload) | Record an odometry + GPS observation | | odometryTrackingRestarted(payload) | Handle AR tracking reset | | arLoopClosureDetected(payload) | Apply loop closure correction | | add2dImage(payload) | Record a camera capture | | markReferencePoint(payload) | Mark a ground-truth reference point | | addMarker / addLine / addArea | Add map elements | | addToHeatMaps / addHeatMapArea | Add heat map data | | recordPhoneHeight | Record floor detection | | addOrUpdateArPlane | Record AR plane | | startEventArea / addCornerToEventArea / finishEventArea | Event area workflow |

Selectors (read from state)

| Export | Description | | ----------------------------- | ------------------------------- | | getAlignmentMatrix(state) | 4×4 alignment matrix or null | | getAlignmentRotation(state) | Alignment quaternion or null | | getOdometryPositions(state) | Recorded odometry positions | | getOdometryRotations(state) | Recorded odometry rotations | | getGpsPositions(state) | Recorded GPS positions | | getReferencePoints(state) | User-defined reference points | | getZeroReference(state) | GPS origin or null | | getGpsAccuracyStats(state) | { median, mean } GPS accuracy |

Math Utilities

| Export | Description | | -------------------------------------------- | ----------------------------------------- | | fusedGpsFromOdom(matrix, odomPos, zeroRef) | AR position → GPS coordinates | | calcRelativeCoordsInMeters(origin, coord) | GPS → local meters offset | | calcGpsCoords(origin, relative) | Local meters → GPS coordinates | | distanceInMeters(a, b) | Haversine distance between two GPS points | | calcGeoHash / geoHashToLatLong | Geohash encoding/decoding | | calcQuadKey / quadKeyToLatLong | Bing Maps quad-key encoding/decoding | | toEarthCenteredCoordinates(coord) | GPS → ECEF |

Serializable Types

Vector3, Quaternion, Matrix4, Vector4, LatLong, LatLongAlt, and conversion helpers (fromVector3, toVector3, fromQuaternion, toQuaternion, fromMatrix4, toMatrix4, etc.).

License Key

| Export | Description | | ----------------------------------- | -------------------------------------- | | validateLicenseKey(key, options?) | Validate an Ed25519-signed license key |

A community license key is included in the open-source companion packages and renewed with each release. See EULA.md §3 — view on npm (open EULA.md) or read the bundled copy at node_modules/gps-plus-slam-js/EULA.md after install.

License

Proprietary — Copyright (c) 2026 cs-util-com. All rights reserved.

This library is distributed as a pre-built package. The full End User License Agreement ships inside the package as EULA.md: view on npm (open EULA.md) or read the bundled copy at node_modules/gps-plus-slam-js/EULA.md after install.

Companion Packages

The open-source companion packages provide a full AR+GPS application framework built on top of this library:

• gps-plus-slam-app-framework — Reusable AR session management, GPS sensors, visualization, and storage utilities (Apache 2.0)
• gps-plus-slam-recorder — Reference AR recording application (Apache 2.0)

Source: github.com/cs-util-com/location-based-webxr