Instance

template<IsSpectral TSpectral>
class Instance : public huira::Node<TSpectral>

Scene graph node representing an instantiable asset (mesh, light, unresolved object, camera model, or model).

Instance nodes are leaf nodes in the scene graph and wrap a single asset pointer.

Template Parameters:

TSpectral – Spectral type (e.g., RGB, Spectral)

Public Functions

inline Instance(Scene<TSpectral> *scene, const Instantiable<TSpectral> &asset)

Construct an Instance node for a given asset.

Parameters:

  • scene – Pointer to the owning Scene

  • asset – Asset to wrap (mesh, light, etc.)

Instance(const Instance&) = delete
Instance &operator=(const Instance&) = delete
inline const Instantiable<TSpectral> &asset() const
inline virtual std::string type() const override

Get the object’s type string.

Returns:

std::string Type

virtual std::string get_info() const override

Get a descriptive string for this instance, including asset info.

Returns:

std::string Info string

void set_position(const Vec3<double> &position)

Set the node’s position manually.

Parameters:

position – Position vector in meters

void set_position(units::Meter x, units::Meter y, units::Meter z)

Set the node’s position manually using unit types.

Parameters:

  • x – X position (meters)

  • y – Y position (meters)

  • z – Z position (meters)

void set_rotation(const Rotation<double> &rotation)

Set the node’s rotation manually.

Parameters:

rotation – Rotation object

void set_scale(const Vec3<double> &scale)

Set the node’s scale.

Parameters:

scale – Scale vector

void set_scale(double sx, double sy, double sz)

Set the node’s scale using individual values.

Parameters:

  • sx – X scale

  • sy – Y scale

  • sz – Z scale

void set_velocity(const Vec3<double> &velocity)

Set the node’s velocity manually.

Parameters:

velocity – Velocity vector in m/s

void set_velocity(units::MetersPerSecond vx, units::MetersPerSecond vy, units::MetersPerSecond vz)

Set the node’s velocity manually using unit types.

Parameters:

  • vx – X velocity (m/s)

  • vy – Y velocity (m/s)

  • vz – Z velocity (m/s)

void set_angular_velocity(const Vec3<double> &angular_velocity)

Set the node’s angular velocity manually.

Parameters:

angular_velocity – Angular velocity vector in rad/s

void set_angular_velocity(units::RadiansPerSecond wx, units::RadiansPerSecond wy, units::RadiansPerSecond wz)

Set the node’s angular velocity manually using unit types.

Parameters:

  • wx – X angular velocity (rad/s)

  • wy – Y angular velocity (rad/s)

  • wz – Z angular velocity (rad/s)

void set_spice_origin(const std::string &spice_origin)

Set the node’s SPICE origin for ephemeris-based transforms.

Parameters:

spice_origin – SPICE origin string

void set_spice_frame(const std::string &spice_frame)

Set the node’s SPICE frame for rotation-based transforms.

Parameters:

spice_frame – SPICE frame string

void set_spice(const std::string &spice_origin, const std::string &spice_frame)

Set both SPICE origin and frame for the node.

Parameters:

  • spice_origin – SPICE origin string

  • spice_frame – SPICE frame string

inline virtual std::uint64_t id() const override

Get the object’s unique ID.

Returns:

std::uint64_t ID

inline TransformMode get_position_mode() const
inline TransformMode get_rotation_mode() const
Transform<double> get_apparent_transform(ObservationMode obs_mode, const Time &t_obs, const Transform<double> &observer_ssb_state) const

Get the apparent transform of the node for a given observation mode and time.

Parameters:

  • obs_mode – Observation mode (true, geometric, aberrated)

  • t_obs – Observation time

  • observer_ssb_state – Observer’s SSB transform

Returns:

Transform<double> Apparent transform

Vec3<double> get_static_position() const
Rotation<double> get_static_rotation() const
Vec3<double> get_static_scale() const
Vec3<double> get_static_velocity() const
Vec3<double> get_static_angular_velocity() const
std::string get_spice_origin() const
std::string get_spice_frame() const
NodeHandle<TSpectral, Node<TSpectral>> get_parent() const

Gets a handle to the parent node.

Returns a base NodeHandle to the parent. This always returns the parent as a base Node type, even if the parent is actually a more specific type like FrameNode.

Throws:

std::runtime_error – If this node has no parent (e.g., root node)

Returns:

NodeHandle<TSpectral, Node<TSpectral>> Handle to the parent node

template<typename TParentNode>
NodeHandle<TSpectral, TParentNode> get_parent_as() const

Gets a handle to the parent node with a specific type.

Returns a handle to the parent cast to the specified node type. This performs a dynamic cast to verify the parent is actually of the requested type at runtime.

Template Parameters:

TParentNode – The expected type of the parent node (e.g., FrameNode<TSpectral>)

Throws:

  • std::runtime_error – If this node has no parent

  • std::runtime_error – If the parent is not of type TParentNode

Returns:

NodeHandle<TSpectral, TParentNode> Handle to the parent with the specified type

inline virtual std::span<const std::shared_ptr<Node<TSpectral>>> get_children() const
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

Protected Functions

bool position_can_be_spice_() const
inline virtual bool position_can_be_manual_() const
bool rotation_can_be_spice_() const
inline virtual bool rotation_can_be_manual_() const
inline void set_parent_(Node<TSpectral> *parent)
std::pair<const Node<TSpectral>*, Transform<double>> find_spice_origin_ancestor_() const

Find the first ancestor (including self) with a SPICE origin.

Throws:

std::runtime_error – if no SPICE origin found in ancestry

Returns:

Pair of (ancestor node, accumulated transform from this to ancestor)

std::pair<const Node<TSpectral>*, std::pair<Rotation<double>, Vec3<double>>> find_spice_frame_ancestor_() const

Find the first ancestor (including self) with a SPICE frame.

Throws:

std::runtime_error – if no SPICE frame found in ancestry

Returns:

Pair of (ancestor node, accumulated rotation from this to ancestor)

std::pair<Transform<double>, double> get_geometric_state_(const Time &t_obs, const Transform<double> &observer_ssb_state, bool iterate, double tol = 1e-12) const

Get the geometric state (transform and light time) of the node.

Parameters:

  • t_obs – Observation time

  • observer_ssb_state – Observer’s SSB transform

  • iterate – Whether to iterate for aberration

  • tol – Tolerance for iteration

Returns:

std::pair<Transform<double>, double> {transform, light time}

Transform<double> get_ssb_transform_(const Time &t_obs, double dt = 0.0) const

Get the node’s transform in the Solar System Barycenter (SSB) frame.

Parameters:

  • t_obs – Observation time

  • dt – Light time delay

Returns:

Transform<double> SSB transform

Transform<double> get_local_position_at_(const Time &t_obs, double dt) const

Get the node’s local position transform at a given time.

Parameters:

  • t_obs – Observation time

  • dt – Light time delay

Returns:

Transform<double> Local position transform

Transform<double> get_local_rotation_at_(const Time &t_obs, double dt) const

Get the node’s local rotation transform at a given time.

Parameters:

  • t_obs – Observation time

  • dt – Light time delay

Returns:

Transform<double> Local rotation transform

Protected Attributes

Transform<double> local_transform_
TransformMode position_mode_ = TransformMode::MANUAL_TRANSFORM
TransformMode rotation_mode_ = TransformMode::MANUAL_TRANSFORM
std::string spice_origin_ = ""
std::string spice_frame_ = ""
std::uint64_t id_ = 0
Scene<TSpectral> *scene_
Node<TSpectral> *parent_ = nullptr

Protected Static Attributes

static std::uint64_t next_id_ = 0