FrameNode

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

Scene graph node that can have children.

FrameNode represents a node in the scene graph that can have child nodes and leaf objects. Provides child management and factory methods for leaf node creation.

Template Parameters:

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

Public Functions

FrameNode(Scene<TSpectral> *scene)

Construct a FrameNode and attach to a Scene.

Parameters:

scene – Pointer to the owning Scene

~FrameNode() override = default
FrameNode(const FrameNode&) = delete
FrameNode &operator=(const FrameNode&) = delete
std::weak_ptr<FrameNode<TSpectral>> new_child()

Create a new child FrameNode and attach it to this node.

Returns:

std::weak_ptr<FrameNode<TSpectral>> Weak pointer to new child

void delete_child(std::weak_ptr<Node<TSpectral>> child)

Delete a child node from this FrameNode.

Parameters:

child_weak – Weak pointer to child node

std::weak_ptr<Instance<TSpectral>> new_instance(Primitive<TSpectral> *primitive)

Create a new Instance leaf node for a primitive and attach it to this FrameNode.

Parameters:

primitive – Primitive pointer

Returns:

std::weak_ptr<Instance<TSpectral>> Weak pointer to new instance

std::weak_ptr<Instance<TSpectral>> new_instance(Light<TSpectral> *light)

Create a new Instance leaf node for a light and attach it to this FrameNode.

Parameters:

light – Light pointer

Returns:

std::weak_ptr<Instance<TSpectral>> Weak pointer to new instance

std::weak_ptr<Instance<TSpectral>> new_instance(UnresolvedObject<TSpectral> *unresolved_object)

Create a new Instance leaf node for an unresolved object and attach it to this FrameNode.

Parameters:

unresolved_object – UnresolvedObject pointer

Returns:

std::weak_ptr<Instance<TSpectral>> Weak pointer to new instance

std::weak_ptr<Instance<TSpectral>> new_instance(CameraModel<TSpectral> *camera_model)

Create a new Instance leaf node for a camera model and attach it to this FrameNode.

Parameters:

camera_model – CameraModel pointer

Returns:

std::weak_ptr<Instance<TSpectral>> Weak pointer to new instance

std::weak_ptr<Instance<TSpectral>> new_instance(Model<TSpectral> *model)

Create a new Instance leaf node for a model and attach it to this FrameNode.

Parameters:

model – Model pointer

Returns:

std::weak_ptr<Instance<TSpectral>> Weak pointer to new instance

inline virtual std::string type() const override

Get the object’s type string.

Returns:

std::string Type

inline virtual std::span<const std::shared_ptr<Node<TSpectral>>> get_children() const override
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, expressed in the PARENT frame.

The angular velocity vector is interpreted in the axes of this node’s parent frame, and the node’s orientation evolves as q(t) = delta(t) * q_0. This is only an “inertial” rate if every ancestor of this node is itself static. To command rates about the node’s own axes (e.g. a roll about a camera boresight), use set_body_angular_velocity() instead.

Parameters:

angular_velocity – Angular velocity vector in rad/s, parent-frame axes

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

Set the node’s angular velocity manually using unit types, expressed in the PARENT frame.

The (wx, wy, wz) components are interpreted in the axes of this node’s parent frame, and the node’s orientation evolves as q(t) = delta(t) * q_0. This is only an “inertial” rate if every ancestor of this node is itself static. To command rates about the node’s own axes (e.g. a roll about a camera boresight), use set_body_angular_velocity() instead.

Parameters:

  • wx – X angular velocity about the parent-frame x-axis (rad/s)

  • wy – Y angular velocity about the parent-frame y-axis (rad/s)

  • wz – Z angular velocity about the parent-frame z-axis (rad/s)

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

Set the node’s angular velocity manually using unit types, expressed in the node’s own BODY frame.

The (wx, wy, wz) components are interpreted in this node’s own axes, and the node’s orientation evolves as q(t) = q_0 * delta(t). For a camera (OpenCV convention, +z = boresight), a pure wz therefore produces a roll about the boresight regardless of how the camera is oriented relative to its parent. To command rates in the parent frame’s axes, use set_angular_velocity() instead.

Parameters:

  • wx – X-body angular velocity (rad/s)

  • wy – Y-body angular velocity (rad/s)

  • wz – Z-body angular velocity (rad/s)

void set_manual_transform(const Transform<double> &transform)
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

template<IsPositionCallback TCallback, typename ...Args>
void set_custom_position_callback(Args&&... args)
void set_keplerian_orbit(units::Meter semi_major_axis, double eccentricity, units::Radian inclination, units::Radian raan, units::Radian arg_periapsis, units::Radian mean_anomaly, Time epoch, double mu)
template<IsRotationCallback TCallback, typename ...Args>
void set_custom_rotation_callback(Args&&... args)
void set_z_up_y_forward_callback()
void set_z_down_y_forward_callback()
template<IsTransformCallback TCallback, typename ...Args>
void set_custom_state_callback(Args&&... args)
inline TransformMode get_position_mode() const
inline TransformMode get_rotation_mode() const
Transform<double> get_apparent_transform(ObservationMode obs_mode, const Time &epoch, 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)

  • epoch – Time that the manually set transform corresponds to

  • 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
inline void set_visible(bool visible = true)

Set whether this node is collected into a SceneView.

Read once, while a SceneView is constructed. An existing SceneView holds its own copy of the collected geometry and its own TLAS, so it is unaffected; construct a new SceneView to render the change.

A hidden node’s descendants are skipped along with it, but their own flags are left alone, so showing this node again restores whatever each descendant was individually set to.

Hiding a light removes its illumination as well as its appearance, and hiding a designated indirect source removes it from next event estimation. Hiding the instance that a SceneView is constructed against does not disable that camera: the observer pose is read from the instance directly rather than through the traversal.

Parameters:

visible – True to collect this node, false to skip it and its descendants.

inline bool is_visible() const

This node’s own flag, which ignores whether an ancestor is hidden.

bool is_effectively_visible() const

True only when this node and every one of its ancestors are visible.

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.

Walk up to the root, checking each node’s visibility flag.

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

Returns:

bool True only if this node and every ancestor are visible

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

Protected Functions

virtual bool position_must_be_spice_() const override

Check if manual position is allowed (no child uses SPICE).

Returns:

bool True if allowed

virtual bool rotation_must_be_spice_() const override

Check if manual rotation is allowed (no child uses SPICE).

Returns:

bool True if allowed

bool position_can_be_spice_() const
bool rotation_can_be_spice_() 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 &epoch, 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:

  • epoch – Time that the manually set transform corresponds to

  • 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 &epoch, const Time &t_obs, double dt = 0.0) const

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

Parameters:

  • epoch – Time that the manually set transform corresponds to

  • t_obs – Observation time

  • dt – Light time delay

Returns:

Transform<double> SSB transform

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

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

Parameters:

  • epoch – Time that the manually set transform corresponds to

  • t_obs – Observation time

  • dt – Light time delay

Returns:

Transform<double> Local position transform

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

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

Parameters:

  • epoch – Time that the manually set transform corresponds to

  • t_obs – Observation time

  • dt – Light time delay

Returns:

Transform<double> Local rotation transform

Protected Attributes

std::vector<std::shared_ptr<Node<TSpectral>>> children_
Transform<double> local_transform_
bool body_frame_rates_ = false

When true, local_transform_.angular_velocity was supplied via set_body_angular_velocity() and is expressed in the node’s own body axes; orientation propagates as q(t) = q_0 * delta. When false (the default), the rates are expressed in the parent frame’s axes and orientation propagates as q(t) = delta * q_0. Note that get_local_rotation_at_() always re-expresses the angular velocity in parent axes before storing it in the returned Transform (the frame Transform::operator* expects).

bool visible_ = true
TransformMode position_mode_ = TransformMode::MANUAL_TRANSFORM
TransformMode rotation_mode_ = TransformMode::MANUAL_TRANSFORM
std::string spice_origin_ = ""
std::string spice_frame_ = ""
std::unique_ptr<PositionCallback> position_callback_
std::unique_ptr<RotationCallback> rotation_callback_
std::unique_ptr<StateCallback> transform_callback_
Scene<TSpectral> *scene_
Node<TSpectral> *parent_ = nullptr

Friends

friend class Scene< TSpectral >
friend class SceneView< TSpectral >