@spec approx_position(t()) :: {float(), float(), float()} | nil

The surveyed a-priori receiver position {x_m, y_m, z_m} (ECEF meters), or nil if the file carries no APPROX POSITION XYZ.

@spec band_frequency_hz(String.t(), String.t()) :: float() | nil

Carrier frequency in hertz for a system letter ("G"/"E"/"C") and a RINEX band digit (the second character of an observation code, e.g. "1" in "L1C").

Returns nil for GLONASS (FDMA — channel-dependent) and unknown bands.

@spec decode_crinex(binary()) :: {:ok, String.t()} | {:error, term()}

Decode Hatanaka CRINEX text into the plain RINEX observation text it expands to. Returns {:ok, rinex_text} or {:error, reason}.

@spec epochs(t()) :: [epoch_entry()]

The epoch list as [%{index:, epoch:, flag:, sat_count:}]. The :epoch is a {{y, mo, d}, {h, mi, second_float}} tuple in the file's time scale — exactly the form Orbis.GNSS.Positioning.solve/4 accepts.

@spec load(String.t()) :: {:ok, t()} | {:error, term()}

Load and parse a RINEX observation file from disk.

The file may be plain RINEX (.rnx) or Hatanaka CRINEX (.crx); the first line is sniffed for the CRINEX marker and decoded if present. Returns {:ok, %Orbis.GNSS.RINEX.Observations{}} or {:error, reason}.

@spec load!(String.t()) :: t()

Like load/1 but raises on failure.

@spec observation_codes(t()) :: %{required(String.t()) => [String.t()]}

The per-constellation observation-code table as a map of system letter to the ordered code list, e.g. %{"G" => ["C1C", ...], "E" => [...]}.

@spec parse(binary()) :: {:ok, t()} | {:error, term()}

Parse plain RINEX 3 observation text into a handle.

@spec parse_auto(binary()) :: {:ok, t()} | {:error, term()}

Parse text, auto-detecting plain RINEX vs CRINEX from the first line.

@spec parse_crinex(binary()) :: {:ok, t()} | {:error, term()}

Decode Hatanaka CRINEX text and parse the result into a handle.

@spec phases(t(), non_neg_integer() | tuple(), keyword()) ::
  {:ok, %{required(String.t()) => [map()]}} | {:error, term()}

Carrier-phase observations for one epoch (the L* codes), keyed by satellite.

Convenience over values/3 that keeps only carrier phase and adds the wavelength and the phase expressed in metres when the carrier frequency is known for the satellite's system and band (GPS, Galileo, BeiDou). For GLONASS the FDMA wavelength depends on the satellite's frequency channel, which is not yet exposed, so wavelength_m/value_m are nil there.

Returns {:ok, %{satellite_id => [phase]}} where each phase is

%{code: "L1C", value_cycles: 1.23e8, lli: 0 | nil, ssi: 7 | nil,
  wavelength_m: 0.1903 | nil, value_m: 2.34e7 | nil}

@spec pseudoranges(t(), non_neg_integer() | tuple(), keyword()) ::
  {:ok, [observation()]} | {:error, term()}

Extract single-frequency pseudoranges for one epoch.

epoch is either the integer epoch index (from epochs/1) or an epoch tuple {{y, mo, d}, {h, mi, s}}, which is resolved to its index.

Without :codes, the version-aware defaults are applied across every system. When :codes is given it defines the whole policy: only the listed systems are extracted, each with its given code preference, e.g. codes: %{"G" => ["C1C"]} yields GPS-only pseudoranges and codes: %{"G" => ["C1C"], "C" => ["C2I"]} yields GPS + BeiDou.

Returns {:ok, [{"G01", range_m}, ...]} (ascending satellite id) or {:error, :epoch_out_of_range} / {:error, :unknown_epoch}.

@spec values(t(), non_neg_integer() | tuple(), keyword()) ::
  {:ok, %{required(String.t()) => [map()]}} | {:error, term()}

Every observation value for one epoch, keyed by satellite.

epoch is the integer index (from epochs/1) or an epoch tuple {{y, mo, d}, {h, mi, s}}. Unlike pseudoranges/3 this returns the raw RINEX observations across code types — pseudorange, carrier phase, Doppler, and signal strength — so callers can build carrier-phase combinations.

Returns {:ok, %{satellite_id => [obs]}} where each obs is

%{code: "L1C", kind: :carrier_phase, value: 1.23e8, units: :cycles,
  lli: 0 | nil, ssi: 7 | nil}

kind/units follow the RINEX code's leading letter (C → :pseudorange/ :meters, L → :carrier_phase/:cycles, D → :doppler/:hz, S → :signal_strength/:db_hz). A blank observation has a nil value. Returns {:error, :epoch_out_of_range} / {:error, :unknown_epoch}.

Options

• :codes — a per-system code filter, e.g. %{"G" => ["L1C", "L2W"]}. By default every code for every satellite is returned; a non-empty filter restricts the result (and the data crossing the NIF boundary) to the listed systems, and within each to the listed codes. A system mapped to [] keeps all of that system's codes — e.g. %{"G" => []} is GPS-only, all codes.