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 – The spectral type (e.g., RGB, Visible8)

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_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_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, expressed in the PARENT frame.

The components are interpreted in the axes of this node’s parent frame; the orientation evolves as q(t) = delta(t) * q_0. This is only an “inertial” rate if every ancestor of the node is 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 – The x-component of angular velocity (parent-frame axes)

  • wy – The y-component of angular velocity (parent-frame axes)

  • wz – The z-component of angular velocity (parent-frame axes)

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

Sets the angular velocity using individual components, expressed in the node’s own BODY frame.

The components are interpreted in this node’s own axes; the orientation evolves as q(t) = q_0 * delta(t). For a camera (OpenCV convention, +z = boresight), a pure wz 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 – The x-body frame component of angular velocity

  • wy – The y-body frame component of angular velocity

  • wz – The z-body frame 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

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

void set_visible(bool visible = true) const

Sets whether this node is collected into a SceneView.

Takes effect for SceneViews constructed after the call; ones that already exist are unaffected. Descendants are skipped along with this node but keep their own flags.

Parameters:

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

bool is_visible() const

Reads this node’s own visibility flag, ignoring any hidden ancestor.

Returns:

bool The flag as last set on this node

bool is_effectively_visible() const

Reports whether this node would be collected, ancestors included.

Returns:

bool True only if this node and every ancestor are visible

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

inline std::string name() const
inline std::uint64_t id() const
inline std::string type() const

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_