ElementSetCatalog

struct ElementSetCatalog

Satellites’ element sets read from a catalog of TLEs or OMMs, with a report of the entries left out of it and why.

A catalog is read in one of the formats CelesTrak and Space-Track publish (ElementSetFormat): TLEs, two lines each or three with a name line, or OMMs in KVN, CSV or JSON. read() works out which from the text, and parse() is told. Each entry is checked as SatRec::from_tle() or SatRec::from_omm() checks it.

An entry that isn’t an element set SGP4 can propagate is skipped, and reported in skipped with the reason, rather than stopping the read: one bad entry in a catalog of thousands shouldn’t cost the rest. ElementSetOptions::strict makes it throw instead. An error that leaves nothing to read, such as a file that can’t be opened or JSON that doesn’t parse, always throws.

A satellite is kept once. Of its element sets, the one whose epoch is nearest ElementSetOptions::reference_time is kept, or with no reference time, the newest; of two as near, or as new, the first. The others are reported as SUPERSEDED. The element sets kept are in the order their satellites first appear in the catalog.

Example

// Today's active satellites, from CelesTrak, leaving out anything a fortnight old or older
const Time now("2026-10-26T12:00:00");
const ElementSetCatalog catalog = ElementSetCatalog::read(
"active.json", {.reference_time = now, .max_age = units::Day(14)});
for (const SkippedElementSet& skipped : catalog.skipped) {
    std::cout << skipped.catalog_number << ": " << skipped.message << "\n";
}

Public Members

std::vector<SatRec> element_sets

The element sets read and kept.

std::vector<ElementSetSource> sources

Where each element set kept came from, in the same order.

std::vector<SkippedElementSet> skipped

The entries left out, and why, in the order of the catalog.

Public Static Functions

static inline ElementSetCatalog read(const std::filesystem::path &path, const ElementSetOptions &options = {})

Reads a catalog of element sets from a file, in the format its text is in (see detect_format()).

Parameters:
  • path – The file.

  • options – Which element sets to keep, and how.

Throws:

std::runtime_error – if the file can’t be read, its text can’t be split into entries, or options.strict is set and an entry isn’t an element set SGP4 can propagate.

Returns:

The element sets kept, and the entries left out.

static inline ElementSetCatalog read(const std::filesystem::path &path, ElementSetFormat format, const ElementSetOptions &options = {})

Reads a catalog of element sets from a file in the format given.

Parameters:
  • path – The file.

  • format – The format of its text.

  • options – Which element sets to keep, and how.

Throws:

std::runtime_error – as the other read() does.

Returns:

The element sets kept, and the entries left out.

static inline ElementSetCatalog parse(std::string_view text, ElementSetFormat format, const ElementSetOptions &options = {})

Reads a catalog of element sets from its text.

Parameters:
  • text – The catalog’s text.

  • format – The format it is in.

  • options – Which element sets to keep, and how.

Throws:

std::runtime_error – if the text can’t be split into entries (JSON that doesn’t parse, or CSV whose header has a quote that isn’t closed), if options.max_age is given without a reference_time or isn’t positive, or if options.strict is set and an entry isn’t an element set SGP4 can propagate.

Returns:

The element sets kept, and the entries left out.

static inline ElementSetFormat detect_format(std::string_view text)

The format a catalog’s text is in, from how it starts.

JSON starts with ‘[’ or ‘{’. KVN starts with a CCSDS_OMM_VERS or COMMENT line, or another KEYWORD = value line. CSV starts with a header row of keywords, with NORAD_CAT_ID among them. Anything else is taken to be TLEs.

Parameters:

text – The catalog’s text.

Returns:

Its format.

struct ElementSetOptions

Which of a catalog’s element sets to keep, and how to read them.

Its fields can be set by name: {.include = {25544}, .max_age = units::Day(14)}.

Public Members

Sgp4Mode mode = Sgp4Mode::AFSPC

The mode to propagate them in. Leave it AFSPC unless you have a reason not to: see Sgp4Mode.

std::vector<int> include = {}

Keep only the satellites with these catalog numbers, or every satellite if it is empty.

std::vector<int> exclude = {}

Leave out the satellites with these catalog numbers.

std::optional<Time> reference_time = {}

When the element sets are to be used. It decides which of a satellite’s element sets is kept (see ElementSetCatalog), and is what max_age is measured from.

std::optional<units::Day> max_age = {}

Leave out element sets whose epoch is further than this from reference_time, before or after it. It needs a reference_time.

bool strict = false

Throw on the first entry that isn’t an element set SGP4 can propagate, rather than skip it.

struct ElementSetSource

Where in a catalog an element set kept from it came from.

Public Members

std::size_t entry = 0

Which entry of the catalog it was, counted from 0.

std::size_t line = 0

The line its entry starts on, counted from 1, or 0 in a JSON catalog.

struct SkippedElementSet

An entry of a catalog that was left out of it, and why.

Public Members

std::size_t entry = 0

Which entry of the catalog it was, counted from 0.

std::size_t line = 0

The line its entry starts on, counted from 1, or 0 in a JSON catalog, which has no lines to speak of.

int catalog_number = 0

Its satellite’s NORAD catalog number, or 0 if it couldn’t be read.

std::string name

Its satellite’s name, or empty if it has none.

SkipReason reason = SkipReason::INVALID
std::string message

Why, in words.

enum class huira::ElementSetFormat

The formats a catalog of element sets is read from, as CelesTrak and Space-Track publish them.

Values:

enumerator TLE

Two-line element sets, each with a name line before it or not (2LE or 3LE).

enumerator OMM_KVN

OMMs in the CCSDS keyword = value notation, each from its CCSDS_OMM_VERS line.

enumerator OMM_CSV

OMMs as CSV: a header row of keywords, then a row for each.

enumerator OMM_JSON

OMMs as JSON: an array of objects of keywords and values, or one object.

enum class huira::SkipReason

Why an entry of a catalog was left out of it.

Values:

enumerator INVALID

It isn’t an element set SGP4 can propagate, or isn’t one at all.

enumerator NOT_INCLUDED

Its satellite isn’t one of ElementSetOptions::include.

enumerator EXCLUDED

Its satellite is one of ElementSetOptions::exclude.

enumerator TOO_OLD

Its epoch is further than ElementSetOptions::max_age from the reference time.

enumerator SUPERSEDED

Another element set for its satellite was kept (see ElementSetCatalog).

enumerator CLAIMED

Something else places its satellite: a node, or another constellation.