feat: satellite visibility & DOP prediction (computeVisibility)

Given broadcast ephemerides, a fixed receiver location and a time
window, computeVisibility returns per-satellite elevation timelines,
per-epoch visible count and PDOP, and discrete rise/peak/set passes —
the computation behind a session-planning tool. Reuses
computeAllPositions/computeDop. Validated against ABMF over a 6 h window.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Author: MiguelPuntoEs

CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog
 
+## Unreleased (1.3.0)
+
+### New features
+
+- **`computeVisibility(ephemerides, rxPos, startMs, endMs, stepSec, maskDeg)`** in `gnss-js/orbit` — satellite visibility and DOP prediction over a time window for a fixed location: per-satellite elevation timelines, visible-count and PDOP per epoch, and discrete rise/peak/set passes. Foundation for session planning.
+
 ## Unreleased (1.2.0)
 
 ### Fixed

README.md

@@ -51,6 +51,16 @@ const { distance } = vincenty(
 // distance in meters, angles in radians
 ```
 
+### Visibility / pass prediction
+
+```ts
+import { computeVisibility } from 'gnss-js/orbit';
+
+const vis = computeVisibility(ephemerides, rxEcef, startMs, endMs, 300, 10);
+// vis.passes: rise/peak/set per satellite; vis.pdop / vis.visibleCount
+// per epoch; vis.elevation[prn]: elevation timeline for plotting.
+```
+
 ### Single-point positioning
 
 ```ts

src/orbit/index.ts

@@ -886,3 +886,121 @@ export function computeLiveSkyPositions(
 
   return result;
 }
+
+/* ================================================================== */
+/*  Visibility / pass prediction                                       */
+/* ================================================================== */
+
+/** A single above-mask visibility interval for one satellite. */
+export interface VisibilityPass {
+  prn: string;
+  system: string;
+  /** Rise time (Unix ms) — first sample at or above the mask. */
+  rise: number;
+  /** Set time (Unix ms) — last sample at or above the mask. */
+  set: number;
+  /** Time of peak elevation (Unix ms). */
+  peakTime: number;
+  /** Peak elevation (radians). */
+  peakEl: number;
+}
+
+export interface VisibilityResult {
+  /** Sample epochs (Unix ms). */
+  times: number[];
+  /** Elevation (radians) per PRN per epoch; null when below −0.05 rad / no eph. */
+  elevation: Record<string, (number | null)[]>;
+  /** Number of satellites at or above the mask, per epoch. */
+  visibleCount: number[];
+  /** PDOP per epoch (null when < 4 satellites above the mask). */
+  pdop: (number | null)[];
+  /** Discrete above-mask passes, sorted by rise time. */
+  passes: VisibilityPass[];
+}
+
+/**
+ * Predict satellite visibility and DOP over a time window for a fixed
+ * receiver location.
+ *
+ * @param ephemerides Broadcast ephemerides covering the window.
+ * @param rxPos Receiver ECEF position (meters).
+ * @param startMs Window start (Unix ms).
+ * @param endMs Window end (Unix ms).
+ * @param stepSec Sample spacing in seconds (default 300).
+ * @param elevationMaskDeg Elevation mask in degrees (default 10).
+ */
+export function computeVisibility(
+  ephemerides: Ephemeris[],
+  rxPos: [number, number, number],
+  startMs: number,
+  endMs: number,
+  stepSec = 300,
+  elevationMaskDeg = 10
+): VisibilityResult {
+  const stepMs = stepSec * 1000;
+  const times: number[] = [];
+  for (let t = startMs; t <= endMs; t += stepMs) times.push(t);
+
+  const maskRad = (elevationMaskDeg * Math.PI) / 180;
+  const all = computeAllPositions(ephemerides, times, rxPos);
+
+  const elevation: Record<string, (number | null)[]> = {};
+  const visibleCount = new Array<number>(times.length).fill(0);
+  const pdop = new Array<number | null>(times.length).fill(null);
+
+  // Per-epoch visible az/el for DOP
+  const visiblePerEpoch: { az: number; el: number }[][] = times.map(() => []);
+
+  for (const prn of all.prns) {
+    const series = all.positions[prn]!;
+    elevation[prn] = series.map((p) => (p ? p.el : null));
+    for (let i = 0; i < series.length; i++) {
+      const p = series[i];
+      if (p && p.el >= maskRad) {
+        visibleCount[i]!++;
+        visiblePerEpoch[i]!.push({ az: p.az, el: p.el });
+      }
+    }
+  }
+
+  for (let i = 0; i < times.length; i++) {
+    const dop = computeDop(visiblePerEpoch[i]!);
+    pdop[i] = dop ? dop.pdop : null;
+  }
+
+  // Extract passes: contiguous runs at or above the mask per PRN
+  const passes: VisibilityPass[] = [];
+  for (const prn of all.prns) {
+    const els = elevation[prn]!;
+    let start = -1;
+    let peakEl = -Infinity;
+    let peakTime = 0;
+    for (let i = 0; i <= els.length; i++) {
+      const el = i < els.length ? els[i] : null;
+      const above = el !== null && el !== undefined && el >= maskRad;
+      if (above) {
+        if (start === -1) {
+          start = i;
+          peakEl = -Infinity;
+        }
+        if (el! > peakEl) {
+          peakEl = el!;
+          peakTime = times[i]!;
+        }
+      } else if (start !== -1) {
+        passes.push({
+          prn,
+          system: prn[0]!,
+          rise: times[start]!,
+          set: times[i - 1]!,
+          peakTime,
+          peakEl,
+        });
+        start = -1;
+      }
+    }
+  }
+  passes.sort((a, b) => a.rise - b.rise);
+
+  return { times, elevation, visibleCount, pdop, passes };
+}

test/visibility.test.ts

@@ -0,0 +1,57 @@
+import { describe, it, expect } from 'vitest';
+import { readFileSync, existsSync } from 'fs';
+import { join } from 'path';
+import { parseNavFile } from '../src/rinex';
+import { computeVisibility } from '../src/orbit';
+
+const DIR = join(__dirname, '../test-fixtures');
+const HAS_DATA = existsSync(join(DIR, 'BRDC.nav'));
+
+// ABMF (Guadeloupe) ECEF, from the obs header used elsewhere in the suite.
+const ABMF: [number, number, number] = [2919785.712, -5383745.067, 1774604.692];
+const START = Date.UTC(2024, 0, 1, 0, 0, 0);
+const END = Date.UTC(2024, 0, 1, 6, 0, 0);
+
+describe.skipIf(!HAS_DATA)('computeVisibility (ABMF, 6 h)', () => {
+  const nav = parseNavFile(readFileSync(join(DIR, 'BRDC.nav'), 'utf-8'));
+  const vis = computeVisibility(nav.ephemerides, ABMF, START, END, 300, 10);
+
+  it('samples the whole window at the requested step', () => {
+    expect(vis.times[0]).toBe(START);
+    expect(vis.times[vis.times.length - 1]).toBe(END);
+    expect(vis.times[1]! - vis.times[0]!).toBe(300_000);
+  });
+
+  it('keeps a healthy sky in view with usable DOP', () => {
+    const mid = Math.floor(vis.times.length / 2);
+    expect(vis.visibleCount[mid]).toBeGreaterThan(6);
+    expect(vis.pdop[mid]).toBeGreaterThan(0.5);
+    expect(vis.pdop[mid]).toBeLessThan(10);
+  });
+
+  it('produces well-formed passes', () => {
+    expect(vis.passes.length).toBeGreaterThan(5);
+    for (const p of vis.passes) {
+      expect(p.set).toBeGreaterThanOrEqual(p.rise);
+      expect(p.peakTime).toBeGreaterThanOrEqual(p.rise);
+      expect(p.peakTime).toBeLessThanOrEqual(p.set);
+      expect(p.peakEl).toBeGreaterThan((10 * Math.PI) / 180);
+      expect(p.peakEl).toBeLessThanOrEqual(Math.PI / 2 + 1e-6);
+    }
+  });
+
+  it('a higher elevation mask never increases visibility', () => {
+    const strict = computeVisibility(
+      nav.ephemerides,
+      ABMF,
+      START,
+      END,
+      300,
+      30
+    );
+    const mid = Math.floor(vis.times.length / 2);
+    expect(strict.visibleCount[mid]!).toBeLessThanOrEqual(
+      vis.visibleCount[mid]!
+    );
+  });
+});