NodeHandle

template<IsSpectral TSpectral, typename TNode>
class NodeHandle : public huira::Handle<TNode>

Handle for referencing and manipulating nodes in the scene graph.

NodeHandle provides safe, type-checked access to scene graph nodes, allowing manipulation of position, velocity, rotation, scale, SPICE parameters, and parent access. It is used for both base Node and derived node types (e.g., FrameNode, Instance).

Template Parameters:

  • TSpectral – Spectral type for the scene

  • TNode – Node type (must derive from Node<TSpectral>)

Public Functions

NodeHandle() = delete
void set_position(units::Meter x, units::Meter y, units::Meter z) const

Sets the position using individual coordinates.

Parameters:

  • x – The x-coordinate

  • y – The y-coordinate

  • z – The z-coordinate

Vec3<double> get_static_position() const

Gets the local position.

Returns:

Vec3<double> The local 3D position vector

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

Sets the velocity using individual components.

Parameters:

  • vx – The x-component of velocity

  • vy – The y-component of velocity

  • vz – The z-component of velocity

Vec3<double> get_static_velocity() const

Gets the local velocity.

Returns:

Vec3<double> The local 3D velocity vector

void set_rotation(const Rotation<double> &rotation) const

Sets the rotation.

Parameters:

rotation – The rotation to set

void set_rotation_local_to_parent(const Mat3<double> &matrix) const

Sets the local-to-parent rotation using a rotation matrix.

Parameters:

matrix – 3x3 rotation matrix

void set_rotation_local_to_parent(const Quaternion<double> &quaternion) const

Sets the local-to-parent rotation using a quaternion.

Parameters:

quaternion – Quaternion representing the rotation

void set_rotation_local_to_parent(const Vec3<double> &axis, units::Degree angle) const

Sets the local-to-parent rotation using an axis and angle.

Parameters:

  • axis – Axis of rotation

  • angle – Angle in degrees

void set_rotation_parent_to_local(const Mat3<double> &matrix) const

Sets the parent-to-local rotation using a rotation matrix.

Parameters:

matrix – 3x3 rotation matrix

void set_rotation_parent_to_local(const Quaternion<double> &quaternion) const

Sets the parent-to-local rotation using a quaternion.

Parameters:

quaternion – Quaternion representing the rotation

void set_rotation_parent_to_local(const Vec3<double> &axis, units::Degree angle) const

Sets the parent-to-local rotation using an axis and angle.

Parameters:

  • axis – Axis of rotation

  • angle – Angle in degrees

void set_euler_angles(units::Radian x, units::Radian y, units::Radian z, std::string sequence = "XYZ") const

Sets the rotation using extrinsic Euler angles and a rotation sequence.

Parameters:

  • x – First Euler angle (radians)

  • y – Second Euler angle (radians)

  • z – Third Euler angle (radians)

  • sequence – Rotation order (e.g., “XYZ”)

Rotation<double> get_static_rotation() const

Gets the local rotation.

Returns:

Rotation<double> The local rotation

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

Sets the angular velocity using individual components.

Parameters:

  • wx – The x-component of angular velocity

  • wy – The y-component of angular velocity

  • wz – The z-component of angular velocity

Vec3<double> get_static_angular_velocity() const

Gets the local angular velocity.

Returns:

Vec3<double> The local 3D angular velocity vector

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

Sets the scale using individual components.

Parameters:

  • sx – The x-component of the scale

  • sy – The y-component of the scale

  • sz – The z-component of the scale

void set_scale(double s) const

Sets the scale using a single scale factor.

Parameters:

s – The 3D scale factor to set

Vec3<double> get_static_scale() const

Gets the local scale.

Returns:

Vec3<double> The local 3D scale

void set_spice_origin(const std::string &spice_origin) const

Sets the SPICE origin identifier.

Parameters:

spice_origin – The SPICE origin string identifier

void set_spice_frame(const std::string &spice_frame) const

Sets the SPICE frame identifier.

Parameters:

spice_frame – The SPICE frame string identifier

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

Sets the SPICE origin and frame identifiers.

Parameters:

  • spice_origin – The SPICE origin string identifier

  • spice_frame – The SPICE frame string identifier

std::string get_spice_origin() const

Gets the SPICE origin identifier.

Returns:

std::string The SPICE origin string identifier

std::string get_spice_frame() const

Gets the SPICE frame identifier.

Returns:

std::string The SPICE frame string identifier

NodeHandle<TSpectral, Node<TSpectral>> get_parent() const

Gets a handle to the parent node.

Returns a base NodeHandle to the parent. This is safe for all node types but may require casting if you need access to parent-specific functionality. For type-specific access, use get_parent_as() instead.

Throws:

std::runtime_error – If this node has no parent

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 is useful when you know the parent’s type and need access to type-specific functionality (e.g., getting a FrameHandle to access frame-specific methods).

Example usage: 

auto frame_parent = camera_handle.get_parent_as<FrameNode<RGB>>();
auto grandparent = frame_parent.get_parent_as<FrameNode<RGB>>();

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

bool valid() const

Checks if the handle points to a valid, scene-owned object.

Returns:

true if valid, false otherwise

std::shared_ptr<U> get() const

Gets a shared_ptr to the referenced object, optionally downcasting to a derived type.

Template Parameters:

U – Type to cast to (default: T)

Throws:

std::runtime_error –

Returns:

std::shared_ptr

Protected Functions

std::shared_ptr<T> get_() const

Gets a shared_ptr to the referenced object, enforcing validity.

Throws:

std::runtime_error – if the handle is invalid

Returns:

std::shared_ptr<T> Shared pointer to the object

Protected Attributes

std::weak_ptr<T> ptr_