Skyline masks and sky geometry

Until 0.36 every Earth visibility test in the engine was one elevation cut-off, mask_deg: a satellite counted when it was at or above one number, whatever its direction. A street, a quay, a fjord or a crane blocks part of the sky and leaves the rest open. A skyline is an elevation cut that depends on azimuth; the sky-geometry functions turn a site, a time, constellations and a skyline into the visible set, the dilution of precision (DOP), the geometry covariance, the horizontal error ellipse, a Monte Carlo cloud and a skyplot. The design is docs/design/2026-10-12-geometry-and-skyline-design.md (items 1 and 2).

Evidence: the masked visibility decision (geodetic look angles, the table mask, the visible set and its DOP) is VALIDATED against Orekit 12.2 and gnss_lib_py 1.0.4 in a pre-registered comparison, and so are the error ellipse and the per-system cofactor (numpy, pre-registered); the canyon, sector and terrain reductions, the presets and the rest of the sky-geometry functions are MODELLED (Evidence). A skyline removes line-of-sight satellites and nothing more. The presets are REPRESENTATIVE geometries, not surveys.

The skyline#

A skyline is the pointwise maximum of four descriptions. Azimuth is degrees clockwise from true north in the site's local east-north-up frame; elevations are in [0, 90).

preset = "<name>" starts from a named geometry; the canyon fields then override the preset's canyon field by field, and table, sectors and terrain add to it.

The receiver's mask_deg keeps its meaning: it is a flat skyline. The effective cut at azimuth az is max(mask_deg, skyline(az)), and a satellite is visible when its elevation is at or above it: the same >= the flat mask always used. A satellite above mask_deg but below the skyline is masked by the skyline.

The street canyon#

A street runs along azimuth s, w metres between the walls, the antenna a metres up on the centreline. Along azimuth az, with θ = az − s, the ray reaches a wall after d(az) = (w/2) / |sin θ|, so a wall of height h cuts at

cut(az) = atan( (h − a) / d(az) )          (the right wall for sin θ > 0, the side at s + 90°)

The open strip lies along the street. With length_m = L (the antenna at the middle) a ray leaves through an open end, and the wall cuts nothing, when d(az) · |cos θ| > L/2. A wall no taller than the antenna cuts nothing. antenna_m defaults to 1.5 m (a car roof or a hand-held receiver, a stated choice); a new canyon needs width_m.

Presets#

Chosen and stated dimensions (the design note's), not surveys of any real place. kshana skyline --preset <name> prints one with its provenance and its cut every degree.

In a scenario#

An optional [skyline] section, over the kind's own cut-off:

The ground site of orbit and integrity. Both kinds model an orbiting user with a geocentric elevation and no Earth-fixed azimuth, so they take a skyline only with the design note's ground-site mode: user_site = { lat_deg, lon_deg, height_m } in place of user (exactly one of the two). Each sample is one absolute instant, epoch + t: every satellite is propagated to it (an element set, broadcast ephemeris or SP3 file is advanced from its own epoch, a Walker satellite counts t from epoch) and rotated to Earth-fixed at it, so the site sees one consistent sky. epoch is the orbit scenario's own; without one (and always for integrity, which has none) it is the newest epoch among the satellites that carry one, or J2000 for Walker patterns only. Elevation and azimuth are geodetic (WGS-84). The horizontal and vertical split of the integrity kind's ARAIM protection levels and Stanford vertical error uses the same geodetic up (the WGS-84 ellipsoid normal, about 0.19° from the geocentric radial at 45° latitude); snapshot RAIM already used it. A user_site without a skyline is a plain ground user; the orbiting user path is unchanged.

kind = "integrity"
mask_deg = 5.0
# ...
[user_site]
lat_deg = 59.45
lon_deg = 24.75
height_m = 15.0

[skyline]
preset = "harbour-approach"

Backward compatibility. Without a [skyline] section a scenario is byte-identical to what the same engine gave before skyline code existed: tests/skyline_scenarios.rs checks the JSON, chart and summary of every shipped scenario that runs one of these kinds, and the NMEA text of every training scenario, against SHA-256 digests of the "0.36 portable" baseline (the 0.35.0 release commit's digests, re-based when the engine moved to portable maths and kept in the test as the record: docs/revisions/STUDIO15-portable-math-rebaseline.md). An empty [skyline] section cuts nothing; the result then equals the run without it except for the added skyline block and the zero masked_by_skyline counts.

What is refused, with the reason in the message: a skyline on an orbiting user; user and user_site together; an unknown preset; a canyon without width_m; a table that is not strictly increasing in [0, 360); an elevation outside [0, 90); an empty sector; a non-positive terrain distance; input over the caps; any unknown key.

The result gains skyline: { source, open_fraction, provenance } when the section is present: source is preset:<name>, preset:<name>+overrides or custom; open_fraction is the fraction of the upper hemisphere's solid angle above max(mask_deg, skyline) (the mean of 1 − sin(cut) over azimuth: 1 for a zero mask, 0.5 for a flat 30° cut); provenance is the preset's line or the scenario's own. Units and provenance classes are in the units block.

Bundled examples (kshana example <name>):

Sky geometry#

Five engine functions (src/geometry.rs), the same on every surface:

A request:

{
  "site": {"lat_deg": 59.91, "lon_deg": 10.75, "height_m": 5},
  "time_s": 3600,
  "systems": ["gps-baseline", "galileo", "beidou-meo", "xona-pulsar"],
  "mask_deg": 5,
  "skyline": {"preset": "fjord"},
  "clock": "per-system",
  "sigma_uere_m": 1.5,
  "confidence": 0.95
}

systems are the engine's constellation presets (constellation-design's gps-baseline, galileo, beidou-meo, glonass, ...; the LEO presets xona-pulsar, iridium-stl, ...) or a full leo-pvt [[system]] table, propagated to time_s (Keplerian with secular J2, the leo-pvt joint-mode orbits). Their relative phases come from different reference epochs, so the sky is a representative geometry, not the sky of that date at that place. Satellites may instead (or as well) be given directly: "satellites": [{"id": "G05", "system": "GPS", "az_deg": 120, "el_deg": 35}, ...], or with "ecef_m": [x, y, z] and a site or user_ecef_m. Defaults: each system's own mask (5° GNSS, 10° LEO; 5° for satellites given directly), one receiver clock per system ("common" for one shared clock), σ_UERE 1 m (a representative dual-frequency budget line), confidence 0.95. Input caps: at most 2000 satellites above the horizon (a system table asking for more is refused before it is built) and 16 receiver clocks.

A dated sky from element sets. "tle" takes two-line element set text (a name line before each set is optional; at most 4 MiB, an input cap), propagated by the engine's SGP4 (WGS-72, the propagator orbit-real-tle uses) to "epoch" plus time_s, rotated to Earth-fixed with UT1 taken as UTC and no polar motion, and seen from site. "epoch" is UTC ISO 8601 (2026-06-07T12:00:00Z) and dates only the element sets (the presets carry no date, so an epoch without tle is refused); "tle_system" labels them for the per-system clock (default TLE). Every result says what sky it is in sky_source and sky_statement:

A mix joins them with +. epoch_utc is the instant the element sets were propagated to, and tle_skipped names what of the text was not used, with the reason: malformed or orphaned element-set lines (with their line numbers), sets the parser refused, and sets SGP4 could not propagate to that instant (decayed, or past its limits); at most 100 entries in all, then one last entry counting the rest. An empty systems list adds no presets. The skyplot states the basis in its footer.

One kernel. The cofactor matrix is orbit::cofactor_from_los, the design-matrix assembly and Gauss-Jordan inverse behind orbit::dop. orbit::dop_cov exposes the covariance and orbit::dop is its reduction, so the VALIDATED scalars are unchanged and still pinned by tests/dop_reference.rs. There is no second DOP implementation.

The ellipse. Semi-axes k σ √λ for the eigenvalues λ of the east-north block, with k = √(−2 ln(1 − p)) (√5.991 = 2.448 at 95 %, 1 at 39.35 %), and the major axis's azimuth ½ atan2(2 Q_EN, Q_NN − Q_EE) in [0, 180) from north.

Every result carries label (MODELLED), the statement (geometry under a stated error model: independent, equal, zero-mean Gaussian range errors; not a prediction of a receiver's real error, which also has biases, multipath and non-line-of-sight errors; not an integrity bound) and the advisory: Advisory software, not type-approved navigation equipment (IEC 61108, IEC 61162): the operator remains responsible for the navigation of the vessel.

Evidence#

Five ledger rows (docs/VERIFICATION-MATRIX.md), as the design note scopes them:

The absence of a [skyline] section is checked byte for byte against the 0.35.0 outputs, which shows backward compatibility and validates nothing. gnss_lib_py applies a single elevation mask only, so it is the DOP oracle here, not the mask oracle.

What a skyline does not model: diffraction over a wall edge, reflections and non-line-of-sight signals a real receiver may still track (they are dropped, not degraded), partial transparency (a lattice crane is opaque across its sector), terrain beyond the points given, and Earth curvature inside the canyon and sector forms.