Instance Handle

template<IsSpectral TSpectral>
class InstanceHandle : public huira::NodeHandle<TSpectral, Instance<TSpectral>>

Handle for referencing an Instance node in the scene graph.

InstanceHandle provides safe, type-checked access to Instance nodes, allowing manipulation and querying of asset instances within the scene. Used by FrameHandle and SceneView for instance management.

Template Parameters:

TSpectral – Spectral type for the scene

Public Functions

InstanceHandle() = 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_

Friends

friend class FrameHandle< TSpectral >
friend class SceneView< TSpectral >