SatRec

class SatRec

A satellite’s element set, read from a two-line element set (TLE) or an Orbit Mean-Elements Message (OMM), and ready to be propagated with SGP4.

A SatRec is made from a TLE’s two lines, or from three with a name line before them, or from an OMM’s fields, and checks them as it is made. For a TLE: each line’s length, the layout of its columns and its checksum, and that both lines are for the same satellite. For an OMM: that it has the fields SGP4 needs, each a number, an integer or a time as it should be, and that its metadata, if given, is for SGP4 in TEME about the Earth. For both: that the elements are in range, and that SGP4 can propagate them at their epoch. Anything else throws, so a SatRec that exists is good at its epoch.

evaluate() gives the satellite’s position and velocity at a time, in the TEME frame (true equator, mean equinox) that SGP4 works in, which Huira defines as the SPICE frame HUIRA_EARTH_TEME, centered on the Earth. SGP4 runs with the WGS-72 constants that TLEs are made with, in the mode chosen when the SatRec is made (see Sgp4Mode).

The time since epoch that SGP4 is given is elapsed ephemeris time (TDB seconds), as SPICE’s own SGP4 (evsgp4_c) takes it, so it counts leap seconds. Software that subtracts UTC Julian dates, as python-sgp4 does, differs from it by a second of motion, several kilometers in low Earth orbit, for each leap second between the epoch and the time.

Catalog numbers in the Alpha-5 form, a letter and four digits for the numbers from 100000 to 339999, are read. SGP4-XP element sets (ephemeris type 4) are not: SGP4 cannot propagate them, so they are rejected rather than propagated wrongly.

evaluate() keeps no state between calls: it can be called from several threads at once, and what it gives does not depend on what it was called with before. Each call propagates from the epoch, which for the resonant deep-space orbits (periods near 12 and 24 hours) means integrating in steps of 720 minutes, so they cost a little more the further from the epoch they are evaluated.

Public Functions

inline int catalog_number() const

The satellite’s NORAD catalog number, decoded from the Alpha-5 form if it is in it.

inline const std::string &name() const

The satellite’s name: from a TLE’s name line, or an OMM’s OBJECT_NAME, or empty if it has none.

inline const std::string &international_designator() const

The satellite’s international designator (COSPAR ID) as a TLE writes it, such as “98067A” (an OMM’s OBJECT_ID “1998-067A”), or empty if the element set leaves it blank.

inline const Time &epoch() const

The epoch of the element set: the time it describes the orbit at.

inline Sgp4Mode mode() const

The mode SGP4 propagates the element set with.

inline std::optional<PositionState> evaluate(const Time &time) const

The satellite’s position and velocity at a time, from SGP4.

Parameters:

time – The time to propagate the element set to.

Returns:

Its position, in meters, and velocity, in meters per second, in the TEME frame (HUIRA_EARTH_TEME, centered on the Earth), or nothing if SGP4 can’t propagate it to the time: most often because it has decayed by then. error_message_at() says why.

inline std::string error_message_at(const Time &time) const

Why SGP4 can’t propagate the element set to a time, if it can’t.

Parameters:

time – The time evaluate() was given.

Returns:

An empty string if evaluate()

gives a state at the time, and otherwise the SGP4 error that stopped it, such as “SGP4 error 6: the satellite has decayed, to below the Earth’s

radius”.

Public Static Functions

static inline SatRec from_tle(std::string_view line1, std::string_view line2, Sgp4Mode mode = Sgp4Mode::AFSPC)

Reads a two-line element set.

Each line may have whitespace before or after it, such as a line ending, which is ignored.

Parameters:
  • line1 – The TLE’s first line, which starts “1 “.

  • line2 – The TLE’s second line, which starts “2 “.

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

Throws:

std::runtime_error – if a line is not 69 characters long, isn’t laid out as a TLE line is, or fails its checksum; if the lines are for different satellites; if the element set is for SGP4-XP; or if SGP4 can’t propagate it at its epoch.

Returns:

The element set, initialized for SGP4.

static inline SatRec from_tle(std::string_view name, std::string_view line1, std::string_view line2, Sgp4Mode mode = Sgp4Mode::AFSPC)

Reads a three-line element set: a name line, then a TLE’s two lines.

The name line may be just the name, as CelesTrak writes it, or start with “0 “, as Space-Track writes it. Whitespace around the name is ignored.

Parameters:
  • name – The satellite’s name line.

  • line1 – The TLE’s first line, which starts “1 “.

  • line2 – The TLE’s second line, which starts “2 “.

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

Throws:

std::runtime_error – as the two-line from_tle() does.

Returns:

The element set, initialized for SGP4.

static inline SatRec from_omm(const OmmFields &fields, Sgp4Mode mode = Sgp4Mode::AFSPC)

Reads an Orbit Mean-Elements Message (OMM): the CCSDS form of a satellite’s mean elements, which CelesTrak and Space-Track publish alongside TLEs, in KVN, XML, JSON and CSV.

Every OMM format comes to its keywords and their values, as text. Of those, SGP4 needs:

Keyword

Value

NORAD_CAT_ID

The catalog number, of up to nine digits

EPOCH

UTC, as YYYY-MM-DDThh:mm:ss.ssssss or YYYY-DDDThh:mm:ss.ssssss

MEAN_MOTION

Revolutions a day

ECCENTRICITY

From 0 to below 1

INCLINATION

Degrees, from 0 to 180

RA_OF_ASC_NODE, ARG_OF_PERICENTER, MEAN_ANOMALY

Degrees

BSTAR

Per Earth radius

MEAN_MOTION_DOT

Revolutions a day squared, as a TLE writes it: half the rate

MEAN_MOTION_DDOT

Revolutions a day cubed, as a TLE writes it: a sixth of the second rate

OBJECT_NAME and OBJECT_ID give the name and international designator. These, if given, are checked: MEAN_ELEMENT_THEORY must be SGP4 (or SGP/SGP4), REF_FRAME TEME, CENTER_NAME EARTH, TIME_SYSTEM UTC, and EPHEMERIS_TYPE not 4. Any other keyword is ignored, so the extra fields Space-Track adds can be passed in as they are.

Numbers are read as C++ reads them in the classic locale, so “1.1606E-05” and “0.000011606” are both fine. An element set read from an OMM made from a TLE propagates as that TLE does: for each of Vallado’s verification cases, to the bit.

Parameters:
  • fields – The OMM’s keywords and values.

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

Throws:

std::runtime_error – if a keyword SGP4 needs is missing, a value isn’t the number, whole number or time it should be, the metadata is for something other than SGP4 in TEME about the Earth, the element set is for SGP4-XP, an element is out of range, or SGP4 can’t propagate it at its epoch.

Returns:

The element set, initialized for SGP4.

Friends

friend struct detail::ElementSetReader
enum class huira::Sgp4Mode

Which of its two behaviors Vallado’s SGP4 propagates an element set with.

Vallado’s reference SGP4 can either reproduce the US Space Force’s operational SGP4 (AFSPC), or use his own handling of the one step where he departs from it (IMPROVED). In the revision Huira vendors, that step is in the periodic perturbations by the Sun and Moon, for orbits whose inclination, as they perturb it, is under 0.2 rad (11.46 degrees). Only deep-space orbits (a period of 225 minutes or more) are perturbed so, which leaves those inclined less than about 11.46 degrees, much of the geostationary belt among them: every other element set is propagated identically in either mode. Where the modes differ, they can be a kilometer apart within hours.

Use AFSPC, the default, unless you have a specific reason not to. TLEs are made by the Space Force fitting observations with its own SGP4, which AFSPC mode reproduces, so they are propagated most faithfully the same way. “Improved” does not mean more accurate for them: it means less consistent with how they were made. Vallado recommends AFSPC mode to match the Space Force’s operations, and made his reference output for SGP4 in it.

IMPROVED is for reproducing software that uses it: python-sgp4 reads every TLE in it (its Satrec.twoline2rv() has no other mode), and Skyfield reads TLEs through python-sgp4. Choose it to compare Huira’s results with theirs exactly, unless a leap second falls between the epoch and the time (see SatRec).

The mode is fixed when a SatRec is made, as SGP4 initializes the element set for it.

Values:

enumerator AFSPC

As the US Space Force’s operational SGP4 does (opsmode ‘a’). The default.

enumerator IMPROVED

Vallado’s improved handling (opsmode ‘i’), as python-sgp4 and Skyfield use.

using huira::OmmFields = std::map<std::string, std::string, std::less<>>

An Orbit Mean-Elements Message’s keywords and their values, as text: “EPOCH”, “MEAN_MOTION”, “BSTAR”, and so on (see SatRec::from_omm()).

Every OMM format (KVN, XML, JSON or CSV) comes to this: each keyword and its value.