Orbis.GNSS.Constellation (Orbis v0.9.1)

Copy Markdown View Source

GNSS constellation identity catalogs and validation helpers.

This module is a data/catalog layer: it builds normalized satellite identity records from public sources and compares those records with GNSS products. It does not alter positioning solves or infer application-specific health rules.

GPS is supported first. CelesTrak gps-ops OMM/JSON is the base source for current NORAD catalog ids and PRN assignments; the PRN is parsed from OBJECT_NAME and rendered as the SP3/RINEX id ("G13"). NAVCEN's GPS constellation page can be parsed and merged as an optional status overlay for SVN and NANU usability details.

Examples

iex> omms = [
...>   %{"OBJECT_NAME" => "GPS BIIF-8  (PRN 03)", "NORAD_CAT_ID" => 40294}
...> ]
iex> {:ok, [record]} = Orbis.GNSS.Constellation.from_celestrak_omm(omms)
iex> {record.system, record.prn, record.norad_id, record.sp3_id}
{:gps, 3, 40294, "G03"}

iex> record = %Orbis.GNSS.Constellation.Record{
...>   system: :gps,
...>   prn: 3,
...>   svn: nil,
...>   norad_id: 40294,
...>   sp3_id: "G03",
...>   active?: true,
...>   usable?: true,
...>   source: %{}
...> }
iex> Orbis.GNSS.Constellation.to_csv([record])
"prn,norad_cat_id,active,sp3_id\n3,40294,true,G03\n"

Live fetching is available through fetch_gps/1, but tests and production pipelines that need deterministic behavior should use from_celestrak_omm/1, parse_navcen_html/1, and merge_navcen/2 with cached bytes.

Summary

Types

error()

Functions

fetch_gps(opts \\ [])

Fetch the current GPS catalog from public sources.

from_celestrak_omm(omms)

Build GPS records from CelesTrak gps-ops OMM/JSON maps.

merge_navcen(records, statuses)

Merge NAVCEN status rows into normalized GPS records by PRN.

parse_navcen_html(html)

Parse NAVCEN's GPS constellation status HTML.

sp3_id(atom, prn)

Render the canonical SP3/RINEX satellite token for a supported GNSS PRN.

to_csv(records, opts \\ [])

Export records as the compact mapping CSV

valid?(report)

Returns true when a validation report has no findings.

validate(records)

Validate catalog identity without an SP3 product.

validate_sp3(records, sp3)

Validate catalog identity against SP3 satellite ids.

validate_sp3!(records, sp3_or_ids)

Validate against SP3 satellite ids and raise unless the catalog is clean.

Types

error()

@type error() ::
  {:error, {:unsupported_system, term()}}
  | {:error, {:bad_celestrak_record, term(), map()}}
  | {:error, {:bad_navcen_html, term()}}
  | {:error, {:navcen_fetch_failed, term()}}
  | {:error, :req_not_available}
  | {:error, term()}

Functions

fetch_gps(opts \\ [])

@spec fetch_gps(keyword()) :: {:ok, [Orbis.GNSS.Constellation.Record.t()]} | error()

Fetch the current GPS catalog from public sources.

CelesTrak gps-ops OMM/JSON is always fetched and used as the base identity source. By default, NAVCEN's GPS constellation table is also fetched and merged as a status/SVN overlay.

Options:

  • :include_navcen - fetch and merge NAVCEN status rows (default: true)
  • :navcen_html - use this already-fetched NAVCEN HTML instead of network access; implies include_navcen: true
  • :timeout_ms - NAVCEN request timeout when fetching the overlay

Returns {:ok, [Record.t()]} or a tagged {:error, reason}.

from_celestrak_omm(omms)

@spec from_celestrak_omm([map()]) ::
  {:ok, [Orbis.GNSS.Constellation.Record.t()]} | error()

Build GPS records from CelesTrak gps-ops OMM/JSON maps.

CelesTrak does not publish SVN in this feed, so records built from this source alone have svn: nil.

merge_navcen(records, statuses)

@spec merge_navcen([Orbis.GNSS.Constellation.Record.t()], [
  Orbis.GNSS.Constellation.NavcenStatus.t()
]) ::
  [Orbis.GNSS.Constellation.Record.t()]

Merge NAVCEN status rows into normalized GPS records by PRN.

NAVCEN does not publish NORAD catalog ids, so CelesTrak remains the identity base. When a PRN is present in both sources, this fills svn, updates usable?, and adds a :navcen entry to the record's source metadata, but only when the CelesTrak object-name block type and NAVCEN block type are compatible. During PRN transitions NAVCEN can still carry a NANU for an older vehicle on the same PRN; those rows are recorded under :navcen_conflict rather than merged into the normalized identity.

parse_navcen_html(html)

@spec parse_navcen_html(String.t()) ::
  {:ok, [Orbis.GNSS.Constellation.NavcenStatus.t()]} | error()

Parse NAVCEN's GPS constellation status HTML.

The parser targets the Drupal table field classes used by NAVCEN's public GPS constellation page. It returns status rows keyed by PRN/SVN; merge them into CelesTrak records with merge_navcen/2.

sp3_id(atom, prn)

@spec sp3_id(:gps, pos_integer()) :: String.t()

Render the canonical SP3/RINEX satellite token for a supported GNSS PRN.

iex> Orbis.GNSS.Constellation.sp3_id(:gps, 7)
"G07"

to_csv(records, opts \\ [])

@spec to_csv(
  [Orbis.GNSS.Constellation.Record.t()],
  keyword()
) :: String.t()

Export records as the compact mapping CSV:

prn,norad_cat_id,active,sp3_id

The active column is true only when record.active? and record.usable? are both true.

Options

  • :booleans - how the active column is rendered: :lower (default — true/false, the conventional CSV form) or :title (True/False, for a consumer such as pandas that reads the column as Python booleans).

valid?(report)

@spec valid?(Orbis.GNSS.Constellation.Validation.t()) :: boolean()

Returns true when a validation report has no findings.

validate(records)

@spec validate([Orbis.GNSS.Constellation.Record.t()]) ::
  Orbis.GNSS.Constellation.Validation.t()

Validate catalog identity without an SP3 product.

Reports duplicate PRNs, duplicate NORAD ids, and PRNs that are inactive or unusable according to the normalized records.

validate_sp3(records, sp3)

@spec validate_sp3(
  [Orbis.GNSS.Constellation.Record.t()],
  Orbis.GNSS.SP3.t() | [String.t()]
) ::
  Orbis.GNSS.Constellation.Validation.t()

Validate catalog identity against SP3 satellite ids.

The second argument may be a loaded %Orbis.GNSS.SP3{} or a list of SP3/RINEX satellite tokens. missing_sp3_ids reports active+usable catalog GPS ids that are absent from the product; extra_sp3_ids reports GPS ids present in the SP3 product but absent from the active+usable catalog.

validate_sp3!(records, sp3_or_ids)

@spec validate_sp3!(
  [Orbis.GNSS.Constellation.Record.t()],
  Orbis.GNSS.SP3.t() | [String.t()]
) :: :ok

Validate against SP3 satellite ids and raise unless the catalog is clean.

A build-time gate: returns :ok when validate_sp3/2 reports no findings, otherwise raises ArgumentError describing them — for example an active-and-usable catalog PRN that is missing from a current SP3 product (a stale-active satellite). Intended for catalog-build / automation steps, not the positioning runtime.