Pose Sources

A node’s position and rotation each come from a source: set by hand (set_position, set_velocity and so on, which hold at the scene view’s reference time), SPICE, or a callback. Callbacks are evaluated while a scene view is built, as many times as it needs, and never while it renders. Each is given a huira::PoseContext and returns the state.

The callbacks Huira provides are a function of the pose context (set_position_function, set_rotation_function), a table of times and states (set_position_table, set_rotation_table), a Keplerian orbit (set_keplerian_orbit), and look_at. A class of one’s own, derived from huira::PositionCallback or huira::RotationCallback, is set with set_custom_position_callback or set_custom_rotation_callback.

struct PoseContext

What a pose is evaluated for, given to every pose callback.

Public Functions

inline PoseContext at(const Time &t) const

The same context at another time.

Public Members

Time time

The time the pose is wanted at: the time of observation, less any light time.

Time reference

The time that poses set by hand hold at: the reference time of the scene view’s interval. A callback that evaluates other nodes passes it on, so that they are placed as the scene view places them.

ObservationMode observation_mode = ObservationMode::ABERRATED_STATE

How the scene view observes the scene.

struct PositionState

A node’s position and velocity, in its parent’s frame.

Public Members

Vec3<double> position = {}

In meters.

Vec3<double> velocity = {}

In meters per second.

struct RotationState

A node’s orientation and angular velocity, relative to its parent.

Public Members

Rotation<double> rotation = {}

From the node’s frame to its parent’s.

Vec3<double> angular_velocity = {}

In radians per second, about the parent’s axes.

struct PositionCallback

Where a node is, as a function of time: the base of the position sources other than SPICE and poses set by hand.

A callback is evaluated many times while a scene view is built, at times in any order (temporal samples, light-time iterations, and estimates of rates), and never while it renders. It must give the same answer for the same context.

Subclassed by huira::KeplerianOrbitCallback, huira::PositionFunctionCallback, huira::PositionTableCallback

Public Functions

virtual ~PositionCallback() = default
virtual PositionState evaluate(const PoseContext &context, const RotationState &rotation) const = 0

The node’s position and velocity in its parent’s frame.

Parameters:

  • context – The time it is wanted at, and how the scene is observed.

  • rotation – The node’s rotation at that time, from its own source: identity if that is a rotation callback, which is evaluated after this one, and given this position.

struct RotationCallback

How a node is oriented, as a function of time: the base of the rotation sources other than SPICE and rotations set by hand. As for PositionCallback, it must give the same answer for the same context.

Subclassed by huira::LookAtCallbackBase< TSpectral >, huira::RotationFunctionCallback, huira::RotationTableCallback, huira::ZDownYForwardCallback, huira::ZUpYForwardCallback

Public Functions

virtual ~RotationCallback() = default
virtual RotationState evaluate(const PoseContext &context, const PositionState &position) const = 0

The node’s rotation and angular velocity relative to its parent.

Parameters:

  • context – The time it is wanted at, and how the scene is observed.

  • position – The node’s position and velocity in its parent’s frame at that time.

struct StateCallback

A node’s whole pose (position, velocity, rotation and angular velocity) relative to its parent, as a function of time. Its scale is the node’s own.

Public Functions

virtual ~StateCallback() = default
virtual Transform<double> evaluate(const PoseContext &context) const = 0

Functions

struct PositionSample

What a position function gives at a time: a position, and a velocity if it has one.

Public Members

Vec3<double> position = {}
std::optional<Vec3<double>> velocity = {}
struct RotationSample

What a rotation function gives at a time: a rotation, and an angular velocity (about the parent’s axes) if it has one.

Public Members

Rotation<double> rotation = {}
std::optional<Vec3<double>> angular_velocity = {}
class PositionFunctionCallback : public huira::PositionCallback

A node’s position from a function of the pose context.

The function gives the position in the parent’s frame, and the velocity if it has one. A velocity it does not give is estimated from the positions RATE_ESTIMATE_SPAN apart, centered on the time.

Public Types

using Function = std::function<PositionSample(const PoseContext&)>

Public Functions

inline PositionFunctionCallback(Function function, std::string what)
Parameters:

  • function – The function giving the position, and the velocity if it has one.

  • what – What the position is of, for errors (the node’s name).

inline virtual PositionState evaluate(const PoseContext &context, const RotationState&) const override

The node’s position and velocity in its parent’s frame.

Parameters:

  • context – The time it is wanted at, and how the scene is observed.

  • rotation – The node’s rotation at that time, from its own source: identity if that is a rotation callback, which is evaluated after this one, and given this position.

class RotationFunctionCallback : public huira::RotationCallback

A node’s rotation from a function of the pose context.

The function gives the rotation relative to the parent, and the angular velocity, about the parent’s axes, if it has one. An angular velocity it does not give is estimated from the rotations RATE_ESTIMATE_SPAN apart, centered on the time.

Public Types

using Function = std::function<RotationSample(const PoseContext&)>

Public Functions

inline RotationFunctionCallback(Function function, std::string what)
Parameters:

  • function – The function giving the rotation, and the angular velocity if it has one.

  • what – What the rotation is of, for errors (the node’s name).

inline virtual RotationState evaluate(const PoseContext &context, const PositionState&) const override

The node’s rotation and angular velocity relative to its parent.

Parameters:

  • context – The time it is wanted at, and how the scene is observed.

  • position – The node’s position and velocity in its parent’s frame at that time.

constexpr double huira::RATE_ESTIMATE_SPAN = 2e-3

How far apart, in seconds, the two times a rate is estimated from are: the rate is the change between them, centered on the time it is wanted at.

The estimate is the change divided by the time between the two times, as Time holds them, so it errs only by how the motion curves between them: by (RATE_ESTIMATE_SPAN / 2)^2 / 6 times its third derivative, about 2e-7 of the rate for something turning at 1 rad/s.

Tables

class PositionTableCallback : public huira::PositionCallback

A node’s position from a table of times and positions, with or without velocities, in its parent’s frame.

Between two entries, the position follows the cubic curve through both that has their velocities there (cubic Hermite interpolation), so the position and velocity are continuous. Velocities that are not given are estimated at each entry from it and its neighbors, by the quadratic through the three (at the ends, through the first or last three): a table taken from motion that is quadratic over each three entries is followed exactly. With two entries, the position runs along the straight line between them.

A time outside the table is an error: nothing is extrapolated.

Public Functions

inline PositionTableCallback(const std::vector<Time> &times, std::vector<Vec3<double>> positions, std::vector<Vec3<double>> velocities, std::string what)
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 to estimate them.

  • what – What the position is of, for errors (the node’s name).

Throws:

std::runtime_error – if there are fewer than two entries, the times are out of order, the sizes differ, or a value is not finite.

inline virtual PositionState evaluate(const PoseContext &context, const RotationState&) const override

The node’s position and velocity in its parent’s frame.

Parameters:

  • context – The time it is wanted at, and how the scene is observed.

  • rotation – The node’s rotation at that time, from its own source: identity if that is a rotation callback, which is evaluated after this one, and given this position.

class RotationTableCallback : public huira::RotationCallback

A node’s rotation from a table of times and rotations, with or without angular velocities, relative to its parent.

Between two entries, the rotation turns from one to the next at a steady rate about a fixed axis, the shorter way round (spherical linear interpolation), as in a SPICE type 3 C-kernel. Its angular velocity is that steady rate, or, where angular velocities are given (about the parent’s axes), theirs interpolated linearly between the two entries. Entries should be close enough that no turn between two is more than half a turn.

A time outside the table is an error: nothing is extrapolated.

Public Functions

inline RotationTableCallback(const std::vector<Time> &times, std::vector<Rotation<double>> rotations, std::vector<Vec3<double>> angular_velocities, std::string what)
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 to take the rate between entries.

  • what – What the rotation is of, for errors (the node’s name).

Throws:

std::runtime_error – if there are fewer than two entries, the times are out of order, the sizes differ, or an angular velocity is not finite.

inline virtual RotationState evaluate(const PoseContext &context, const PositionState&) const override

The node’s rotation and angular velocity relative to its parent.

Parameters:

  • context – The time it is wanted at, and how the scene is observed.

  • position – The node’s position and velocity in its parent’s frame at that time.

Rotation vectors

inline Vec3<double> huira::rotation_vector(const Rotation<double> &rotation)

A rotation as its rotation vector: its axis times its angle, the shorter way round, in the frame it rotates (for a change of a node’s rotation, its parent’s).

Found from its quaternion, so it is precise at any angle, however small.

inline Rotation<double> huira::rotation_from_vector(const Vec3<double> &vector)

The rotation by a rotation vector: about its direction, by its length in radians.