FrameHandle

template<IsSpectral TSpectral>
class FrameHandle : public huira::NodeHandle<TSpectral, FrameNode<TSpectral>>

Handle for manipulating frame nodes in the scene graph.

FrameHandle provides methods to create and delete subframes, manage SPICE subframes, and instantiate or delete asset instances within a frame node. It is a strongly-typed handle that ensures safe access and modification of the scene graph hierarchy.

Template Parameters:

TSpectral – Spectral type for the scene

Subclassed by huira::RootFrameHandle< TSpectral >

Public Functions

FrameHandle() = delete
FrameHandle<TSpectral> new_subframe() const

Creates a new subframe as a child of this frame.

Returns:

FrameHandle<TSpectral> Handle to the new subframe

FrameHandle<TSpectral> new_spice_subframe(const std::string &spice_origin, const std::string &spice_frame) const

Creates a new subframe and sets its SPICE origin and frame.

Parameters:

  • spice_origin – SPICE origin string

  • spice_frame – SPICE frame string

Returns:

FrameHandle<TSpectral> Handle to the new SPICE subframe

void delete_subframe(FrameHandle<TSpectral> subframe) const

Deletes a subframe from this frame.

Parameters:

subframe – Handle to the subframe to delete

template<typename THandle>
InstanceHandle<TSpectral> new_instance(const THandle &asset_handle) const

Creates a new instance of an asset in this frame.

Template Parameters:

THandle – Asset handle type

Parameters:

asset_handle – Handle to the asset to instantiate

Returns:

InstanceHandle<TSpectral> Handle to the new instance

void delete_instance(InstanceHandle<TSpectral> instance) const

Deletes an instance from this frame.

Parameters:

instance – Handle to the instance to 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

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_