Constellation

template<IsSpectral TSpectral>
class Constellation : public huira::SceneObject<Constellation<TSpectral>>

Satellites, many of them, each placed by SGP4 from its element set and seen as a point.

A constellation is a scene’s way of rendering a population of satellites, such as a catalog of every object in Earth orbit from CelesTrak or Space-Track, without a node for each. Each satellite is placed as a node in the scene’s TEME frame would be by Node::set_tle_position(), and seen as an instance of one unresolved object, the same for all: a Lambertian sphere lit by the Sun, say, or a fixed brightness. A scene view places them all at once, in parallel, at as many temporal samples as each one’s motion needs (see SceneView).

A constellation holds one element set for each satellite, as the scene does: a satellite is placed once, by a node or as one of a constellation’s. add() and load() leave out, and report, satellites that something else in the scene places already, and replace the element sets of those the constellation holds itself, so that loading a newer catalog brings it up to date. A satellite remove()d, or a constellation deleted, can then be placed by something else.

Its satellites are placed by SPICE’s ephemeris of the Earth, as the TEME frame is: rendering them needs an SPK with it, such as de440s.bsp. A satellite SGP4 can’t place during an exposure (one that has decayed, most often) is left out of that scene view, with a warning, rather than stopping it (see SceneView::skipped_satellites()).

Make one with Scene::new_constellation(), and use it through a ConstellationHandle.

Template Parameters:

TSpectral – The spectral type (e.g., RGB, Visible8)

Public Functions

Constellation(Scene<TSpectral> *scene, std::shared_ptr<UnresolvedObject<TSpectral>> unresolved_object)

Construct an empty constellation, whose satellites are seen as an unresolved object.

Scene::new_constellation() makes it, and loads Huira’s frame kernel, which defines the TEME frame’s axes, as Scene::teme_frame() does.

Parameters:
  • scene – The scene it is in.

  • unresolved_object – What each satellite is seen as.

Throws:

std::runtime_error – if there is no unresolved object.

Constellation(const Constellation&) = delete
Constellation &operator=(const Constellation&) = delete
ConstellationReport add(const std::vector<SatRec> &element_sets)

Add satellites, from their element sets, or bring those it holds up to date.

Each satellite new to the constellation is added, unless a node or another constellation places it already (it is then left out, and reported as SkipReason::CLAIMED). A satellite it holds has its element set replaced. They are taken in the order given: a later element set for the same satellite replaces an earlier one.

Parameters:

element_sets – The satellites’ element sets (see SatRec, and ElementSetCatalog for reading many).

Returns:

The satellites added, those replaced, and those left out.

ConstellationReport add(const ElementSetCatalog &catalog)

Add the satellites of a catalog that was read, or bring those it holds up to date.

As add() with its element sets, with the entries the catalog’s read left out reported too, and each element set left out identified by where it is in the catalog.

Parameters:

catalog – The catalog read (see ElementSetCatalog::read()).

Returns:

The satellites added, those replaced, and those left out, by the read or here.

ConstellationReport load(const std::filesystem::path &path, const ElementSetOptions &options = {})

Read a catalog of element sets from a file, and add its satellites, or bring those it holds up to date.

Parameters:
Throws:

std::runtime_error – as ElementSetCatalog::read() does.

Returns:

The satellites added, those replaced, and those left out, by the read or here.

ConstellationReport load(const std::filesystem::path &path, ElementSetFormat format, const ElementSetOptions &options = {})

Read a catalog of element sets from a file in the format given, and add its satellites, or bring those it holds up to date.

Parameters:
  • path – The file.

  • format – The format of its text.

  • options – Which of its element sets to read, and how (see ElementSetOptions).

Throws:

std::runtime_error – as ElementSetCatalog::read() does.

Returns:

The satellites added, those replaced, and those left out, by the read or here.

bool remove(int catalog_number)

Remove a satellite, which something else in the scene can then place.

Parameters:

catalog_number – The satellite’s NORAD catalog number.

Returns:

Whether it held the satellite.

void clear()

Remove every satellite.

inline std::size_t size() const

The number of satellites it holds.

bool contains(int catalog_number) const

Whether it holds a satellite.

Parameters:

catalog_number – The satellite’s NORAD catalog number.

const SatRec &element_set(int catalog_number) const

The element set it holds for a satellite.

Parameters:

catalog_number – The satellite’s NORAD catalog number.

Throws:

std::runtime_error – if it doesn’t hold the satellite.

Returns:

Its element set.

std::vector<SatRec> element_sets() const

The element sets it holds, one for each satellite, in no particular order.

void set_unresolved_object(std::shared_ptr<UnresolvedObject<TSpectral>> unresolved_object)

Set the unresolved object each satellite is seen as.

Each satellite is an instance of it, resolved for where that satellite is: a Lambertian sphere lit by the Sun is bright or faint by its phase, and dark in the Earth’s shadow, if the Earth is in the scene to cast one. A scene view resolves the satellites in parallel, so the object must be safe to resolve from several threads at once, as Huira’s own are.

Parameters:

unresolved_object – What each satellite is seen as.

Throws:

std::runtime_error – if there is no unresolved object.

inline const std::shared_ptr<UnresolvedObject<TSpectral>> &unresolved_object() const

The unresolved object each satellite is seen as.

inline void set_visible(bool visible)

Show or hide its satellites: a scene view leaves out those of a hidden constellation.

inline bool is_visible() const

Whether its satellites are shown.

inline virtual std::string type() const override

Get the object’s type string.

Returns:

std::string Type

inline bool is_scene_owned() const

Check if the object is owned by the scene.

Returns:

bool True if owned

inline void set_scene_owned(bool owned)

Set scene ownership flag.

Parameters:

owned – True if owned

inline std::string name() const

Get the object’s name.

Returns:

std::string Name

inline virtual std::uint64_t id() const

Get the object’s unique ID.

Returns:

std::uint64_t ID

inline virtual std::string get_info() const

Get a descriptive info string for the object.

Returns:

std::string Info string

struct ConstellationReport

What adding element sets to a constellation did.

Public Members

std::size_t added = 0

The satellites added to it.

std::size_t replaced = 0

The satellites it already held, whose element sets were replaced.

std::vector<SkippedElementSet> skipped

The element sets left out, and why, in the order they were given: those a catalog’s read left out (see ElementSetCatalog), and those for satellites something else in the scene places already (SkipReason::CLAIMED). An element set given to add() as one of a list is identified by its place in the list, as its entry, with no line.

struct SkippedSatellite

A satellite of a constellation that a scene view left out, as SGP4 can’t place it at some time during the exposure: most often, because it has decayed.

Public Members

std::uint64_t constellation_id = NO_OBJECT_ID

Its constellation.

int catalog_number = 0

Its NORAD catalog number.

std::string name

Its name, or empty.

std::string message

Why, in words.

template<IsSpectral TSpectral>
struct UnresolvedInstance

Instance of an unresolved object in a scene view.

Template Parameters:

TSpectral – The spectral type (e.g., RGB, Visible8)

Public Members

std::shared_ptr<UnresolvedObject<TSpectral>> unresolved_object
std::uint64_t instance_id = NO_OBJECT_ID
std::vector<Transform<float>> transforms
std::vector<Time> times
std::vector<TSpectral> irradiances
std::uint64_t constellation_id = NO_OBJECT_ID

For a satellite of a constellation, which no instance places (its instance_id is NO_OBJECT_ID): the constellation, and the satellite’s NORAD catalog number.

int catalog_number = 0