gnss-js 1.22.0 → 1.24.0

package/dist/positioning.d.ts

@@ -34,6 +34,405 @@ interface KlobucharCoeffs {
  */
 declare function klobucharDelay(coeffs: KlobucharCoeffs, latRad: number, lonRad: number, azRad: number, elRad: number, gpsTowSec: number): number;
 
+/**
+ * RTK positioning, stage 1: epoch-wise double-differenced (DD)
+ * processing of a base/rover receiver pair.
+ *
+ * Two solvers share the same DD construction:
+ *
+ * - `solveDgnss` — code-based DGNSS: between-receiver single
+ *   differences on pseudoranges, double-differenced against a
+ *   reference satellite (highest elevation per signal group), iterated
+ *   weighted least squares for the rover position with the full DD
+ *   covariance (DDs sharing a reference satellite are correlated).
+ *
+ * - `RtkFloatEngine` — a stateful extended Kalman filter over DD
+ *   carrier phase + code with one float DD ambiguity state per
+ *   satellite/signal. An EKF (rather than epoch-wise iterated least
+ *   squares with appended ambiguity columns) was chosen because the
+ *   float ambiguities must persist across epochs anyway, and stage 2
+ *   (LAMBDA) needs the joint float ambiguity covariance — which the
+ *   EKF maintains natively. This mirrors RTKLIB's float-filter
+ *   structure (rtkpos.c), which the implementation was validated
+ *   against.
+ *
+ * Stage 2 — integer ambiguity resolution (opt-in via
+ * `ambiguityResolution: 'instant'`): after each float update the
+ * engine extracts the DD ambiguity subvector and its joint covariance
+ * from the filter, runs MLAMBDA (`lambdaSearch`, a port of RTKLIB's
+ * lambda.c) and validates the best candidate with the ratio test
+ * (s₂/s₁ ≥ `ratioThreshold`, default 3.0 — RTKLIB's default). On
+ * acceptance the rover position is conditioned on the integer
+ * ambiguities (xa = x − P_xb·Q_b⁻¹·(b − ǎ), RTKLIB rtkpos.c
+ * `resamb_LAMBDA`) and reported as a FIXED solution; the filter state
+ * itself is *not* modified (instant, per-epoch fixing — RTKLIB's
+ * `armode=instantaneous`; continuous AR/fix-and-hold, which feed the
+ * fix back into the filter, are stage-3 continuity options). When the
+ * full set fails the ratio test, partial fixing retries after
+ * dropping the lowest-elevation ambiguity, one at a time, down to
+ * half the candidate set (and never below `minFixAmbiguities`) — an
+ * elevation-ordered subset walk in the spirit of RTKLIB demo5's
+ * satellite exclusion, floored so an unconverged float cannot buy a
+ * lucky ratio on a tiny subset. GLONASS ambiguities are excluded from
+ * fixing by
+ * default (DD IFB is only integer-safe across same-model receivers;
+ * enable with `glonassAr`).
+ *
+ * Differencing model: for satellites s and reference r observed by
+ * rover R and base B, the DD pseudorange/phase cancels satellite
+ * clocks (single difference) and receiver clocks (double difference).
+ * On short baselines the ionospheric and most of the tropospheric
+ * delay cancel too; the residual troposphere is modelled by the same
+ * simple elevation-mapped zenith model `solveSpp` uses, applied
+ * differentially. DDs are formed per *signal group* (constellation
+ * letter + RINEX code, e.g. `G1C`, `C2I`) so that only like signals
+ * are differenced.
+ *
+ * GLONASS (FDMA): DD phase is formed in metres with per-satellite
+ * wavelengths (λ_s·SDφ_s − λ_r·SDφ_r). The common receiver clock
+ * term cancels exactly (λ·f = c on every channel); the per-channel
+ * receiver phase bias (inter-frequency bias, IFB) does not, but it is
+ * constant while lock holds and is absorbed into the float DD
+ * ambiguity — the standard reason GLONASS float works while GLONASS
+ * integer fixing is hard. DD *code* retains the differential
+ * inter-channel code bias between the two receivers, which is small
+ * (well below the code noise) for same-model receivers — IFB-safe
+ * enough for stage 1, and documented as such.
+ *
+ * Time convention: `timeMs` is GPS-scale epoch milliseconds, exactly
+ * as produced by `parseNovatelRange` / the RINEX and RTCM parsers —
+ * the same convention `solveSpp` uses. No system clock is read.
+ *
+ * Adapting decoder output (see `toRtkEpoch`):
+ * - NovAtel: `parseNovatelRange(bytes).epochs[i]` gives
+ *   `{ timeMs, meas }`; `toRtkEpoch(meas)` picks each satellite's
+ *   L1-band measurement. When a log carries both RANGE and RANGECMP
+ *   the same epoch appears twice — keep one epoch per `timeMs`.
+ * - RTCM MSM: for each satellite/signal cell build
+ *   `{ code, pr: pseudorangeM, cp: phaserangeM / lambda, lockTimeMs }`
+ *   (MSM phaseranges are metres; divide by the carrier wavelength to
+ *   get cycles) and pass a `prn → measurement` map for the epoch.
+ */
+
+/** One satellite's measurement on one signal, for one epoch. */
+interface RtkMeasurement {
+    /** RINEX band+attribute, e.g. "1C", "2I". */
+    code: string;
+    /** Pseudorange (m). */
+    pr: number | null;
+    /** Carrier phase (cycles, RINEX sign), optional — DGNSS needs none. */
+    cp?: number | null;
+    /** Continuous lock time (ms) for cycle-slip detection, optional. */
+    lockTimeMs?: number;
+    /** GLONASS frequency channel k (−7…+6), for FDMA wavelengths. */
+    gloChannel?: number | null;
+}
+/** One epoch of measurements: PRN → measurement (one signal per PRN). */
+type RtkEpochMeasurements = ReadonlyMap<string, RtkMeasurement>;
+/** Decoder-shaped observation (structurally `NovatelMeasurement`). */
+interface RawObservation {
+    prn: string;
+    code: string;
+    pr: number | null;
+    cp?: number | null;
+    lockTimeS?: number;
+    gloChannel?: number | null;
+}
+/**
+ * Adapt one epoch of decoder observations (e.g.
+ * `parseNovatelRange(...).epochs[i].meas`) to the RTK input map:
+ * keeps each satellite's preferred L1-band code measurement with a
+ * valid pseudorange, drops unsupported systems (SBAS, NavIC).
+ */
+declare function toRtkEpoch(meas: readonly RawObservation[]): Map<string, RtkMeasurement>;
+/** Ephemeris source: a per-PRN map, or a list searched per epoch. */
+type EphemerisSource = ReadonlyMap<string, Ephemeris> | readonly Ephemeris[];
+interface DgnssOptions {
+    /** Elevation mask at the base, degrees. Default 10. */
+    elevationMaskDeg?: number;
+    /** Model the differential troposphere. Default true. */
+    troposphere?: boolean;
+    /** Maximum Gauss-Newton iterations. Default 15. */
+    maxIterations?: number;
+    /** Convergence threshold on the position update (m). Default 1e-4. */
+    convergenceM?: number;
+    /** Zenith code sigma per receiver (m). Default 0.3. */
+    codeSigmaM?: number;
+    /** Worst-first DD residual rejection threshold (m). Default 20. */
+    rejectThresholdM?: number;
+    /** Initial rover position; defaults to the base position. */
+    initialPosition?: [number, number, number];
+}
+interface DgnssSolution {
+    /** Rover position, ECEF metres. */
+    position: [number, number, number];
+    /** Baseline rover − base, ECEF metres. */
+    baseline: [number, number, number];
+    /** Formal position sigmas from the LSQ covariance, ECEF metres. */
+    sigmas: [number, number, number];
+    /** Satellites used (including references). */
+    usedSatellites: string[];
+    /** Reference satellite per signal group. */
+    refSatellites: Record<string, string>;
+    /** Post-fit DD residual (m) per non-reference PRN. */
+    residuals: Record<string, number>;
+    /** Satellites rejected by the residual screen. */
+    rejectedSatellites: string[];
+    nSats: number;
+    iterations: number;
+    converged: boolean;
+}
+/**
+ * Solve the rover position from one epoch of DD pseudoranges.
+ *
+ * @param rover Rover measurements (PRN → measurement).
+ * @param base Base measurements (PRN → measurement, same codes).
+ * @param basePos Known base position, ECEF metres.
+ * @param ephemerides Broadcast ephemerides (per-PRN map, or a list
+ *   searched by closest epoch — pass `parseNovatelNav(...).ephemerides`
+ *   or `parseNavFile(...).ephemerides` directly).
+ * @param timeMs Receiver epoch, GPS-scale milliseconds.
+ */
+declare function solveDgnss(rover: RtkEpochMeasurements, base: RtkEpochMeasurements, basePos: readonly [number, number, number], ephemerides: EphemerisSource, timeMs: number, opts?: DgnssOptions): DgnssSolution | null;
+interface RtkFloatOptions {
+    /**
+     * 'static': the rover position is a constant state (random walk
+     * `processNoisePosM`·√s, default 0). 'kinematic': the position is
+     * re-initialised each epoch with `kinematicSigmaM` uncertainty
+     * (no velocity states at stage 1 — RTKLIB's default kinematic
+     * handling without doppler). Default 'kinematic'.
+     */
+    mode?: 'static' | 'kinematic';
+    /** Elevation mask at the base, degrees. Default 10. */
+    elevationMaskDeg?: number;
+    /** Model the differential troposphere. Default true. */
+    troposphere?: boolean;
+    /** Zenith code sigma per receiver (m). Default 0.3. */
+    codeSigmaM?: number;
+    /** Zenith phase sigma per receiver (m). Default 0.003. */
+    phaseSigmaM?: number;
+    /** Static-mode position random walk (m/√s). Default 0. */
+    processNoisePosM?: number;
+    /** Kinematic per-epoch position reset sigma (m). Default 30. */
+    kinematicSigmaM?: number;
+    /** Ambiguity random walk (cycles/√s). Default 1e-4. */
+    ambProcessNoiseCycles?: number;
+    /** New float ambiguity sigma (cycles). Default 30. */
+    ambInitSigmaCycles?: number;
+    /** Drop ambiguity states unseen for this long (ms). Default 10000. */
+    maxGapMs?: number;
+    /** DD code innovation gate (m): drop the satellite. Default 30. */
+    codeGateM?: number;
+    /**
+     * Phase-minus-code innovation divergence gate (m): treat as an
+     * undetected cycle slip and re-initialise the ambiguity. Default 5.
+     */
+    slipGateM?: number;
+    /** Measurement-update relinearisations (IEKF). Default 2. */
+    updateIterations?: number;
+    /**
+     * Integer ambiguity resolution: 'off' keeps the stage-1 float-only
+     * behaviour; 'instant' attempts a per-epoch LAMBDA fix after each
+     * float update (no state feedback — RTKLIB `armode=instantaneous`).
+     * Default 'off'.
+     */
+    ambiguityResolution?: 'off' | 'instant';
+    /** Ratio-test acceptance threshold (s₂/s₁). Default 3.0 (RTKLIB). */
+    ratioThreshold?: number;
+    /**
+     * Additional elevation mask (deg) for ambiguities entering the fix
+     * (RTKLIB `elmaskar`); 0 = use every measured ambiguity. Default 0.
+     */
+    arElevationMaskDeg?: number;
+    /**
+     * Include GLONASS FDMA ambiguities in the integer fix. Only sound
+     * across same-model receivers (differential IFB). Default false.
+     */
+    glonassAr?: boolean;
+    /**
+     * Partial fixing: when the full ambiguity set fails the ratio test,
+     * drop the lowest-elevation ambiguity and retry (elevation-ordered
+     * subset walk), never below half the candidates. Default true.
+     */
+    partialFixing?: boolean;
+    /** Minimum DD ambiguities to attempt/accept a fix. Default 4. */
+    minFixAmbiguities?: number;
+}
+interface RtkFloatSolution {
+    /** Epoch, GPS-scale milliseconds. */
+    timeMs: number;
+    /**
+     * Rover position, ECEF metres — the ambiguity-fixed position when
+     * `status === 'fixed'`, the float filter position otherwise.
+     */
+    position: [number, number, number];
+    /** Float baseline rover − base, ECEF metres (always the float). */
+    floatBaseline: [number, number, number];
+    /**
+     * Solution quality: 'fixed' when LAMBDA passed the ratio test,
+     * 'float' when carrier ambiguities contributed but no (accepted)
+     * fix, 'dgnss' when the epoch was updated from code DDs only.
+     */
+    status: 'fixed' | 'float' | 'dgnss';
+    /** Satellites contributing DD rows this epoch (incl. references). */
+    nSats: number;
+    /**
+     * Ambiguity-validation ratio (s₂/s₁ of the LAMBDA candidates,
+     * capped at 999.9 as RTKLIB): the accepted subset's ratio when
+     * fixed, the full-set ratio otherwise. Undefined when no fix was
+     * attempted (`ambiguityResolution: 'off'` or no eligible set).
+     */
+    ratio?: number;
+    /** Number of integer-fixed DD ambiguities (when `status==='fixed'`). */
+    nFixed?: number;
+    /** Fixed baseline rover − base, ECEF metres (when fixed). */
+    fixedBaseline?: [number, number, number];
+    /** Integer DD ambiguity (cycles) per fixed PRN (when fixed). */
+    fixedAmbiguities?: Record<string, number>;
+    /** Formal position sigmas (filter covariance), ECEF metres. */
+    sigmas: [number, number, number];
+    /** Float DD ambiguity (cycles) per non-reference PRN. */
+    ambiguities: Record<string, number>;
+    /** Reference satellite per signal group. */
+    refSatellites: Record<string, string>;
+}
+/**
+ * Epoch-by-epoch float RTK filter: EKF states = rover position
+ * (static or kinematic) + one float DD ambiguity (cycles) per
+ * satellite/signal. Cycle slips are handled via lock-time regressions
+ * (LLI-style resets) and a phase/code divergence gate; reference-
+ * satellite switches re-map the DD ambiguity states algebraically
+ * (N_i' = N_i − N_r', old reference gains −N_r') so no information is
+ * lost. Feed epochs in time order via `process`.
+ */
+declare class RtkFloatEngine {
+    private readonly basePos;
+    private readonly ephemerides;
+    private readonly o;
+    /** State vector [x, y, z, N₁…] and covariance; null before init. */
+    private x;
+    private P;
+    private amb;
+    private refs;
+    private track;
+    private lastMs;
+    constructor(basePos: readonly [number, number, number], ephemerides: EphemerisSource, opts?: RtkFloatOptions);
+    /** Clear all filter state (position, ambiguities, lock history). */
+    reset(): void;
+    private ambIndex;
+    /** Remove one ambiguity state (row/col) from x and P. */
+    private dropAmb;
+    /** Append an ambiguity state with the given value and variance. */
+    private addAmb;
+    /**
+     * Re-map a group's DD ambiguities from the old reference r to the
+     * new reference r' (which must hold a state): N_i' = N_i − N_r' and
+     * the old reference's slot becomes N_r = −N_r'. Exact linear
+     * transform of state and covariance (P' = T P Tᵀ).
+     */
+    private retarget;
+    /**
+     * Try to fix the ambiguity subset `idxs` (indices into `this.amb`):
+     * extract the float subvector b and covariance Q_b from the filter,
+     * run MLAMBDA and, without touching the filter state, condition the
+     * position on the best integer candidate,
+     *   xa = x − P_xb·Q_b⁻¹·(b − ǎ)
+     * (RTKLIB rtkpos.c `resamb_LAMBDA`). Returns null when Q_b is not
+     * positive definite / invertible or the search fails; ratio
+     * validation is the caller's job.
+     */
+    private tryFix;
+    /**
+     * Process one synchronized epoch (same nominal `timeMs` for both
+     * receivers). Returns null until a first position can be
+     * initialised (via an internal DGNSS solve) or when the epoch has
+     * fewer than 3 usable DD rows.
+     */
+    process(rover: RtkEpochMeasurements, base: RtkEpochMeasurements, timeMs: number): RtkFloatSolution | null;
+}
+
+/**
+ * Integer ambiguity resolution: LAMBDA decorrelation + MLAMBDA
+ * integer least-squares search.
+ *
+ * Port of RTKLIB's `lambda.c` (demo5 / rtklibexplorer fork,
+ * src/lambda.c, Copyright (c) 2007-2008 T. Takasu, BSD-2-Clause),
+ * cross-checked against the reference papers where the C comments are
+ * thin:
+ *
+ * - [1] P.J.G. Teunissen, "The least-squares ambiguity decorrelation
+ *   adjustment: a method for fast GPS ambiguity estimation",
+ *   J. Geodesy 70, 65-82, 1995.
+ * - [2] X.-W. Chang, X. Yang, T. Zhou, "MLAMBDA: A modified LAMBDA
+ *   method for integer least-squares estimation", J. Geodesy 79,
+ *   552-565, 2005.
+ *
+ * Pipeline (identical to RTKLIB's `lambda()`):
+ * 1. LᵀDL factorization of the float covariance, Q = Lᵀ·diag(D)·L
+ *    with L unit lower triangular (RTKLIB's `LD`).
+ * 2. LAMBDA reduction [1]: integer Gauss transformations interleaved
+ *    with symmetric permutations until the transformed D is
+ *    (approximately) descending — producing a unimodular Z with
+ *    Qz = ZᵀQZ = Lᵀ·diag(D)·L far better conditioned than Q.
+ * 3. MLAMBDA search [2] in the decorrelated space: depth-first
+ *    enumeration over a shrinking ellipsoid, keeping the `m` smallest
+ *    residual quadratic forms (z−ž)ᵀQz⁻¹(z−ž).
+ * 4. Back-transform the candidates to the original space, a = Z⁻ᵀ·ž
+ *    (RTKLIB solves ZᵀF = E; Z is unimodular so F is exactly integer).
+ *
+ * Deviations from lambda.c:
+ * - matrices are `Float64Array` in the same column-major layout, with
+ *   allocation-failure paths dropped (JS throws instead),
+ * - failures (non-positive-definite Q, search loop overflow) return
+ *   `null` instead of a status code + stderr message,
+ * - back-transformed candidates are rounded to the nearest integer:
+ *   F = Z⁻ᵀ·ž is exactly integer in ℤ arithmetic and the rounding only
+ *   removes the ~1e-12 fuzz of the floating-point triangular solve,
+ * - the ratio s₂/s₁ used by the RTKLIB caller (`rtkpos.c`) is returned
+ *   alongside the candidates (∞ when s₁ = 0, i.e. noise-free input).
+ */
+/** Result of an integer least-squares search. */
+interface LambdaResult {
+    /**
+     * The `m` best integer candidate vectors (length n each), sorted by
+     * ascending residual quadratic form; `candidates[0]` is the integer
+     * least-squares minimizer.
+     */
+    candidates: Float64Array[];
+    /**
+     * Residual quadratic forms sᵢ = (a−ǎᵢ)ᵀQ⁻¹(a−ǎᵢ) matching
+     * `candidates`, ascending.
+     */
+    residuals: Float64Array;
+    /**
+     * Ratio-test statistic s₂/s₁ (second-best over best); `Infinity`
+     * when the best residual is exactly 0 (noise-free input). Callers
+     * typically cap it (RTKLIB uses 999.9) before thresholding.
+     */
+    ratio: number;
+}
+/**
+ * LAMBDA/MLAMBDA integer least-squares estimation (RTKLIB `lambda`):
+ * decorrelate the float ambiguities, search the `m` best integer
+ * vectors and back-transform them to the original space.
+ *
+ * @param a Float ambiguities (length ≥ n).
+ * @param Q Their covariance, n×n (symmetric — row/column-major agree).
+ * @param n Number of ambiguities.
+ * @param m Number of candidates to return (default 2: best +
+ *   second-best, what the ratio test needs).
+ * @returns Candidates + residuals + ratio, or null when Q is not
+ *   positive definite or the search does not terminate.
+ */
+declare function lambdaSearch(a: Float64Array, Q: Float64Array, n: number, m?: number): LambdaResult | null;
+/**
+ * LAMBDA reduction only (RTKLIB `lambda_reduction`): the unimodular
+ * decorrelation matrix Z (n×n, column-major) such that Qz = ZᵀQZ is
+ * (near-)diagonally dominant. Exposed for diagnostics/tests; returns
+ * null when Q is not positive definite.
+ */
+declare function lambdaReduction(Q: Float64Array, n: number): Float64Array | null;
+
 /**
  * Single-point positioning (SPP) from pseudoranges and broadcast
  * ephemerides.
@@ -114,4 +513,4 @@ declare function ionoFree(p1: number, p2: number, f1: number, f2: number): numbe
  */
 declare function solveSpp(pseudoranges: Map<string, number>, ephemerides: Map<string, Ephemeris>, timeMs: number, opts?: SppOptions): SppSolution | null;
 
-export { type KlobucharCoeffs, type SppOptions, type SppSolution, ionoFree, klobucharDelay, satClockCorrection, solveSpp };
+export { type DgnssOptions, type DgnssSolution, type EphemerisSource, type KlobucharCoeffs, type LambdaResult, type RawObservation, type RtkEpochMeasurements, RtkFloatEngine, type RtkFloatOptions, type RtkFloatSolution, type RtkMeasurement, type SppOptions, type SppSolution, ionoFree, klobucharDelay, lambdaReduction, lambdaSearch, satClockCorrection, solveDgnss, solveSpp, toRtkEpoch };

package/dist/positioning.js

@@ -1,18 +1,28 @@
 import {
+  RtkFloatEngine,
   ionoFree,
   klobucharDelay,
+  lambdaReduction,
+  lambdaSearch,
   satClockCorrection,
-  solveSpp
-} from "./chunk-B5LU4746.js";
-import "./chunk-JNFV5BYB.js";
+  solveDgnss,
+  solveSpp,
+  toRtkEpoch
+} from "./chunk-T2ZMNRCY.js";
+import "./chunk-MHGNKSSH.js";
 import "./chunk-37QNKGTC.js";
 import "./chunk-6FAL6P4G.js";
 import "./chunk-HVXYFUCB.js";
 import "./chunk-LEEU5OIO.js";
 import "./chunk-FIEWO4J4.js";
 export {
+  RtkFloatEngine,
   ionoFree,
   klobucharDelay,
+  lambdaReduction,
+  lambdaSearch,
   satClockCorrection,
-  solveSpp
+  solveDgnss,
+  solveSpp,
+  toRtkEpoch
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gnss-js",
-  "version": "1.22.0",
+  "version": "1.24.0",
   "description": "Comprehensive GNSS library for JavaScript — time scales, coordinates, RINEX parsing, RTCM3 decoding, orbit computation, and signal analysis",
   "type": "module",
   "sideEffects": false,