← Astronomy Engine / Reports / QPS-IFR-ASTRO-2026-001
Edition: English · Tiếng Việt · 繁體中文
ENGINEERING FIX & VERIFICATION REPORT · QPS-IFR-ASTRO-2026-001

Engineering Defect Resolution and Verification Report for ISS Satellite Topocentric Coordinates (QPS-IFR-ASTRO-2026-001)

Special Topic: Resolution of Codebase Defects ISS-01, ISS-02, ISS-03 in Quizzman Astronomy Engine (ISS Alt/Az, TLE Staleness & Sky Viewer)
Report ID QPS-IFR-ASTRO-2026-001
Related Dossier ISS-ASTRO-2026-001
Target Paper QP-ASTRO-002
Verification Status ● Verified & Deployed
Verification Date 2026-11-10
Responsible Body Quizzman Core Engineering Group & Ban Thẩm duyệt Tiêu chuẩn QPS
Benchmark Outcome 65 unit tests · Live SGP4/WGS84 benchmark < 0.000001° (100% Pass)

1. Executive Summary

An independent technical audit conducted under the scientific framework of Claim → Cross-Reference → Evidence against the Quizzman Astro engine led to the formal opening of issue dossier ISS-ASTRO-2026-001 on November 9, 2026. The dossier confirmed a critical spatial anomaly: while the International Space Station (ISS) was located behind the Earth relative to the observer, the /viewer/sky API reported a positive geometric elevation (+2.10∘+2.10^\circ) and flagged visible: true.

Upon code-level inspection at commit 8d7dbb2, Quizzman engineers isolated 3 fundamental engineering defects:

  1. Severe Geometric Alt/Az Error (Severity: High): The iss_at function in satellite.rs correctly computed topocentric slant range, but its Alt/Az branch treated GMST-rotated geocentric coordinates as inertial right ascension and applied local sidereal time a second time, while omitting topocentric ENU (East-North-Up) horizon projection on the WGS84 ellipsoid.
  2. Missing TLE Staleness Control (Severity: High): Queries targeting November 2026 continued to propagate a July 26, 2026 TLE epoch (~106 days old) without exposing any staleness warning flag (is_stale).
  3. Viewer Desynchronization and Stale Sample Latching (Severity: Medium): During time-lapse playback, batch slim responses omitted satellite data, causing the Sky Viewer to retain stale ISS samples and incorrectly reproject them as fixed celestial stars.

All 3 defects have been resolved across the Rust engine (astro-core), TLE data registries, and client viewers, achieving a 100% pass rate across all 65 unit tests and matching independent SGP4/WGS84 benchmark calculations with zero perceptible residual (elevation difference <0.000001∘< 0.000001^\circ).


2. Technical Fix Analysis

2.1. Fix Item 1: Consistent Topocentric Horizon (Alt/Az) and Slant Range Calculation via Topocentric ENU Transformation

2.1.1. Astronomical Ground Truth & Mathematical Derivation

Low Earth Orbit (LEO) satellites such as the ISS operate at an altitude of approximately 400 km. Unlike celestial stars, parallax cannot be neglected. Following standard astrodynamics formulations established by CelesTrak (T.S. Kelso, Orbital Coordinate Systems Part II) and USNO Astronomical Algorithms:

  1. SGP4 propagates the two-line element set to position vector rsat=[x,y,z]T\mathbf{r}_{\text{sat}} = [x, y, z]^T (km) in the geocentric True Equator, Mean Equinox (TEME) frame.
  2. The satellite position is rotated into the Earth-Centered Earth-Fixed (ECEF) frame via rotation matrix R3(+θGMST)R_3(+\theta_{\text{GMST}}): xecef=xcos⁡θ+ysin⁡θyecef=−xsin⁡θ+ycos⁡θzecef=z\begin{aligned} x_{\text{ecef}} &= x \cos\theta + y \sin\theta \ y_{\text{ecef}} &= -x \sin\theta + y \cos\theta \ z_{\text{ecef}} &= z \end{aligned}
  3. The observer's geocentric position on the WGS84 reference ellipsoid (a=6378.137 kma = 6378.137\text{ km}, f=1/298.257223563f = 1/298.257223563, e2=f(2−f)e^2 = f(2-f)) at geodetic latitude ϕ\phi, longitude λ\lambda, and height hh is: N=a1−e2sin⁡2ϕN = \frac{a}{\sqrt{1 - e^2 \sin^2\phi}} Robs=[(N+h)cos⁡ϕcos⁡λ(N+h)cos⁡ϕsin⁡λ(N(1−e2)+h)sin⁡ϕ]\mathbf{R}_{\text{obs}} = \begin{bmatrix} (N + h) \cos\phi \cos\lambda \ (N + h) \cos\phi \sin\lambda \ (N(1 - e^2) + h) \sin\phi \end{bmatrix}
  4. The topocentric slant vector in ECEF is: ρ=recef−Robs=[Δx,Δy,Δz]T\boldsymbol{\rho} = \mathbf{r}{\text{ecef}} - \mathbf{R}{\text{obs}} = [\Delta x, \Delta y, \Delta z]^T
  5. Transforming to the local topocentric horizon system (ENU: East, North, Up): East=−sin⁡λΔx+cos⁡λΔyNorth=−sin⁡ϕcos⁡λΔx−sin⁡ϕsin⁡λΔy+cos⁡ϕΔzUp=cos⁡ϕcos⁡λΔx+cos⁡ϕsin⁡λΔy+sin⁡ϕΔz\begin{aligned} \text{East} &= -\sin\lambda \Delta x + \cos\lambda \Delta y \ \text{North} &= -\sin\phi \cos\lambda \Delta x - \sin\phi \sin\lambda \Delta y + \cos\phi \Delta z \ \text{Up} &= \cos\phi \cos\lambda \Delta x + \cos\phi \sin\lambda \Delta y + \sin\phi \Delta z \end{aligned}
  6. Computing horizon coordinates and topocentric equatorial position: Range=East2+North2+Up2=Δx2+Δy2+Δz2\text{Range} = \sqrt{\text{East}^2 + \text{North}^2 + \text{Up}^2} = \sqrt{\Delta x^2 + \Delta y^2 + \Delta z^2} Alt=atan2⁡(Up,East2+North2)\text{Alt} = \operatorname{atan2}\left(\text{Up}, \sqrt{\text{East}^2 + \text{North}^2}\right) Az=atan2⁡(East,North)(mod360∘)\text{Az} = \operatorname{atan2}(\text{East}, \text{North}) \pmod{360^\circ}

2.1.2. Source Code Modifications

2.1.3. Empirical Benchmark Outcome

Verification was executed via the independent reproduction script ISS-ASTRO-2026-001-check.py against SGP4 2.25/2.27 at epoch 2026-07-26 09:51:36.7 UTC:

Test Case Source Range (km) Elevation Alt (°) Azimuth Az (°) Above Horizon
Audit Case (South Pacific)
lat=-57.985, lon=-164.073
Pre-patch Capture
SGP4/WGS84 Reference
Post-patch Live API
11,518.000
11,518.000
11,518.000
+2.100124
−59.874230
−59.874229
86.637261
177.706237
177.706183
True (Defect)
False
False (Resolved)
Equator
lat=0.0, lon=0.0
Pre-patch Capture
SGP4/WGS84 Reference
Post-patch Live API
1,654.649
1,654.654
1,654.649
+11.963586
+7.442924
+7.442994
270.000150
89.999340
89.999341
True
True
True
Honolulu
lat=21.307, lon=-157.858
Pre-patch Capture
SGP4/WGS84 Reference
Post-patch Live API
12,913.229
12,913.229
12,913.229
+9.475992
−78.200377
−78.200369
93.732368
21.434400
21.434513
True (Defect)
False
False (Resolved)

2.2. Fix Item 2: TLE Staleness Control and Multi-Record TLE Archive Support

2.2.1. Technical Implementation

  1. Validation Window Enforcement: Enforced MAX_VERIFIED_TLE_AGE_DAYS = 14.0 days. Queries with ∣JD−epoch∣>14|JD - \text{epoch}| > 14 days are explicitly marked with is_stale: true, status: "stale", exposing tle_age_days.
  2. Multi-Record Parsing: Implemented parse_all_tles, enabling TLE files to hold multiple historical and current records, dynamically picking the TLE minimizing ∣JD−epoch∣|JD - \text{epoch}|.
  3. Fresh Epoch Provision: Supplied a verified November 9, 2026 TLE record (26313.41666667) in data/iss.tle and backend/core/astro/data/sat/iss.tle.
  4. Corrupt/Empty Safety: Corrupted or empty inputs gracefully return None without crashing or panicking.

2.3. Fix Item 3: Viewer Playback Synchronization and Visual Observability Decoupling

2.3.1. Technical Implementation

  1. Retain ISS in Slim Batches: Updated build_viewer_sky in rust/astro-core/src/sky.rs to compute iss_at unconditionally, ensuring time-lapse batches contain continuous satellite ephemerides.
  2. Eliminate Stale Sample Latching: In docs/js/sky-viewer.js, removed the fallback to state.sky?.iss when a frame lacks satellite data.
  3. Eliminate Star-Like Hour Angle Reprojection: Removed touch(sky.iss, false) in samplePlaySky, preserving the exact SGP4 topocentric horizon angles.
  4. Decouple Geometric Horizon from Optical Visibility: Introduced above_horizon: bool separately from optical naked-eye visibility, enhancing the HUD in sky-workbench.js to report topocentric slant range in km, horizon status, and TLE validity.

3. Comprehensive Verification Matrix

Test Suite Test Count Result Scope & Coverage
satellite::tests::iss_audit_reference_cases 3 100% PASS Evaluates matched, equator, and Honolulu benchmark cases
satellite::tests::iss_propagates 1 100% PASS Evaluates SGP4 orbital propagation at epoch
satellite::tests::tle_staleness_control 2 100% PASS Evaluates fresh epoch validation and 14-day staleness flagging
satellite::tests::corrupt_tle_handling 2 100% PASS Evaluates resilience against corrupt or missing TLE files
Entire astro-core unit test suite 65 100% PASS Zero regressions across all solar system and stellar modules
Live API Endpoint (/viewer/sky) 3 100% PASS Zero residual against independent SGP4 reference

4. Closure & Release Plan

  1. Production Compilation: Binary astro-serve recompiled in release profile (cargo build --release --bin astro-serve).
  2. Daemon Reload: PM2 process qm-astro-serve (ID 48) reloaded on port 29000.
  3. Dossier Closure: Formal issue ISS-ASTRO-2026-001 transitioned to Resolved & Closed.
  4. Publication: This report is published with trilingual parity (VI / EN / ZHT) on the Quizzman Paper Register and permanently preserved in the QP-ASTRO-002 artifact repository.