TemeFrameNode¶
-
template<IsSpectral TSpectral>
class TemeFrameNode : public huira::FrameNode<TSpectral>¶ A scene’s TEME frame: centered on the Earth, with the axes of the True Equator, Mean Equinox of date frame, in which SGP4 gives the states of objects from their NORAD element sets.
SPICE places it, at EARTH, with the axes of HUIRA_EARTH_TEME, which Huira’s frame kernel (kernels/fk/huira_teme.tf in the data directory) defines from the IAU 1976 precession and IAU 1980 nutation models. Those reproduce Vallado’s teme2eci to within 0.2 mas. Rendering anything in it needs an SPK with the Earth’s ephemeris, such as de440s.bsp, as for any node that SPICE places.
Its pose is fixed: it cannot be moved, rotated or scaled, nor its SPICE origin or frame changed. What it holds can be placed freely. Scene::teme_frame() makes it, keeping one per scene, under the root.
- Template Parameters:
TSpectral – The spectral type (e.g., RGB, Visible8)
Public Functions
-
TemeFrameNode(Scene<TSpectral> *scene)¶
Construct a scene’s TEME frame, placed by SPICE at EARTH with the axes of HUIRA_EARTH_TEME.
Its pose is set here, directly: its setters refuse, as it is fixed. Scene::teme_frame() makes it, attaches it to the root, and loads the frame kernel.
- Parameters:
scene – Pointer to the owning Scene
-
~TemeFrameNode() override = default¶
-
inline virtual std::string type() const override¶
Get the object’s type string.
- Returns:
std::string Type
-
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
-
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: each component finite and not 0 (a negative one mirrors).
- Throws:
std::runtime_error – if a component is 0, too small to invert, or not finite.
-
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
- Throws:
std::runtime_error – if one is 0, too small to invert, or not finite.
-
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_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)¶ Place the node by a position callback of a class of one’s own, made from the arguments given.
Its evaluate() gives the node’s position and velocity in its parent’s frame for a pose context (see PositionCallback). It replaces the node’s position source: a position set by hand, a SPICE origin, or another callback.
- Template Parameters:
TCallback – A class derived from PositionCallback.
- Throws:
std::runtime_error – if a child of the node is placed by SPICE, which places its children only under nodes placed by SPICE.
-
template<typename TFunction>
void set_position_function(TFunction function)¶ Place the node by a function of the pose context.
The function is called with a PoseContext, whose time is when the position is wanted, and returns the node’s position in its parent’s frame, in meters: a Vec3<double>, whose velocity is then estimated from nearby times, or a PositionState (position and velocity, in meters per second), or a PositionSample. It is called many times while a scene view is built, at times in any order, and never while it renders. It must give the same answer for the same context.
- Throws:
std::runtime_error – if a child of the node is placed by SPICE.
-
void set_position_table(const std::vector<Time> ×, std::vector<Vec3<double>> positions, std::vector<Vec3<double>> velocities = {})¶
Place the node by a table of times and positions, with or without velocities, in its parent’s frame (see PositionTableCallback).
- Parameters:
times – When each entry is: at least two, each later than the one before.
positions – The position at each time, in meters.
velocities – The velocity at each time, in meters per second, or none (the default) to estimate them from the positions.
- Throws:
std::runtime_error – if the table is not valid, or a child of the node is placed by SPICE.
-
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, units::CubicKilometersPerSecondSquared mu)¶
Move the node on a Keplerian orbit about its parent, by CSPICE’s conics_c().
- Parameters:
semi_major_axis – The semi-major axis: positive for an ellipse (eccentricity under 1), negative for a hyperbola (over 1).
eccentricity – Non-negative, and not 1: a parabola has no semi-major axis.
inclination, raan, arg_periapsis, mean_anomaly – Angles, finite.
epoch – When the body is at mean_anomaly.
mu – The central body’s standard gravitational parameter, GM (the Earth’s is 398600.4418_Km3ps2); positive.
- Throws:
std::runtime_error – if any element is not finite, or they do not describe an orbit whose periapsis is a positive distance away, about a body of positive mass.
-
void set_tle_position(const SatRec &satrec)¶
Place the node by SGP4, from a satellite’s two-line element set (TLE).
SGP4 gives states in the TEME frame, so the node must be a child of the scene’s TEME frame (Scene::teme_frame()). Whatever else the node has, such as children, a camera, or a rotation source, which this leaves alone, moves with it. A satellite places one node: to place more than one thing with it, make them children of that node.
The scene holds one element set for each satellite. Calling this again for the same satellite, on the same node, replaces it: with a newer TLE, for example. No other node can be placed by the satellite until this one is deleted or given another position source, nor can a constellation hold it (see Constellation), and a satellite a constellation holds can’t place a node.
SGP4 is evaluated as a scene view is built. If it can’t place the satellite at a time the view needs, most often because it has decayed by then, building the view throws.
- Parameters:
satrec – The satellite’s element set (see SatRec::from_tle()).
- Throws:
std::runtime_error – if the node isn’t a child of its scene’s TEME frame, if another node is placed by the same satellite or a constellation holds it, or if a child of the node is placed by SPICE.
-
template<IsRotationCallback TCallback, typename ...Args>
void set_custom_rotation_callback(Args&&... args)¶ Orient the node by a rotation callback of a class of one’s own, made from the arguments given.
Its evaluate() gives the node’s rotation and angular velocity relative to its parent for a pose context and the node’s position (see RotationCallback). It replaces the node’s rotation source: a rotation set by hand, a SPICE frame, or another callback, such as look_at().
- Template Parameters:
TCallback – A class derived from RotationCallback.
- Throws:
std::runtime_error – if a child of the node is oriented by SPICE, which orients its children only under nodes oriented by SPICE.
-
template<typename TFunction>
void set_rotation_function(TFunction function)¶ Orient the node by a function of the pose context.
The function is called with a PoseContext, whose time is when the rotation is wanted, and returns the node’s rotation relative to its parent: a Rotation<double>, whose angular velocity is then estimated from nearby times, or a RotationState (rotation and angular velocity, in radians per second about the parent’s axes), or a RotationSample. It is called many times while a scene view is built, at times in any order, and never while it renders. It must give the same answer for the same context.
- Throws:
std::runtime_error – if a child of the node is oriented by SPICE.
-
void set_rotation_table(const std::vector<Time> ×, std::vector<Rotation<double>> rotations, std::vector<Vec3<double>> angular_velocities = {})¶
Orient the node by a table of times and rotations, with or without angular velocities, relative to its parent (see RotationTableCallback).
- Parameters:
times – When each entry is: at least two, each later than the one before.
rotations – The rotation at each time, from the node’s frame to its parent’s.
angular_velocities – The angular velocity at each time, in radians per second about the parent’s axes, or none (the default) to take the steady rate between entries.
- Throws:
std::runtime_error – if the table is not valid, or a child of the node is oriented by SPICE.
-
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)¶ Place and orient the node by a state callback of a class of one’s own, made from the arguments given.
Its evaluate() gives the node’s whole pose relative to its parent for a pose context (see StateCallback). It replaces both the node’s position source and its rotation source. A position source set afterwards, such as set_position(), replaces only the position, and the callback still gives the rotation; likewise the other way round.
- Template Parameters:
TCallback – A class derived from StateCallback.
- Throws:
std::runtime_error – if a child of the node is placed or oriented by SPICE, which places and orients its children only under nodes it places and orients.
-
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
-
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
-
inline bool has_parent() const¶
Whether the node has a parent: every node but the scene’s root frame does.
-
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 performs a dynamic cast to verify the parent is actually of the requested type at runtime.
- 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
-
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.
Walk up to the root, checking each node’s visibility flag.
- 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
Public Static Attributes
-
static constexpr const char *SPICE_ORIGIN = "EARTH"¶
Its SPICE origin.
Protected Functions
-
inline virtual bool pose_is_fixed_() const override¶
Whether the node’s pose is fixed from when it is made: true for a scene’s TEME frame (see TemeFrameNode). Every setter of a fixed node’s position, rotation, scale, motion, pose source and SPICE origin and frame throws.
-
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
-
void check_scale_(const Vec3<double> &scale) const¶
Throws unless each component of a scale is finite, and so is its inverse, which the inverse transform takes: 0 would flatten the node.
-
void check_pose_can_change_(const std::string &what) const¶
Throws if the node’s pose is fixed (see pose_is_fixed_()), saying what could not be done.
Throws if the node’s pose is fixed (see pose_is_fixed_()):
whatis what could not be done.
-
bool position_can_be_spice_() const¶
-
bool rotation_can_be_spice_() const¶
-
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 PoseContext &context, const Transform<double> &observer_ssb_state, double tol = 1e-12) const¶
Get the geometric state (transform and light time) of the node.
- Parameters:
context – The observation time, the time poses set by hand hold at, and the observation mode: light time is solved for unless it is TRUE_STATE
observer_ssb_state – Observer’s SSB transform
tol – Tolerance for iteration
- Returns:
std::pair<Transform<double>, double> {transform, light time}
-
Transform<double> get_ssb_transform_(const PoseContext &context, double dt = 0.0) const¶
Get the node’s transform in the Solar System Barycenter (SSB) frame.
- Parameters:
context – The observation time, the time poses set by hand hold at, and the observation mode, which callbacks are given (at the emission 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:
- 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:
- Returns:
Transform<double> Local rotation transform
Protected Attributes
-
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_¶