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
skippedwith 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<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.
-
std::vector<ElementSetSource> sources¶
-
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.
-
Sgp4Mode mode = Sgp4Mode::AFSPC¶
-
struct ElementSetSource¶
Where in a catalog an element set kept from it came from.
-
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.
-
std::size_t entry = 0¶
-
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.
-
enumerator TLE¶
-
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.
-
enumerator INVALID¶