Class FrameToFrame

Class FrameToFrame#

Nested Relationships#

Nested Types#

Inheritance Relationships#

Base Type#

Derived Types#

Class Documentation#

class FrameToFrame : public Karana::Core::LockingBase#

Represents a connection between two frames.

This class handles the transformation, velocity, and acceleration between two frames.

See Coordinate Frames for more discussion on the frames layer.

Subclassed by Karana::Frame::ChainedFrameToFrame, Karana::Frame::EdgeFrameToFrame, Karana::Frame::OrientedChainedFrameToFrame

Public Functions

virtual ~FrameToFrame()#

FrameToFrame destructor.

const kc::ks_ptr<Frame> &oframe() const#

Get the oframe of the FrameToFrame.

Returns:

oframe.

const kc::ks_ptr<Frame> &pframe() const#

Get the pframe of the FrameToFrame.

Returns:

pframe.

std::optional<bool> subchainOrientation(const FrameToFrame &sub_f_to_f) const#

Check the relationship of a sub-chain FrameToFrame’s path with respect to the overall FrameToFrame path.

Return true if the sub-chain FrameToFrame’s path is contained in the FrameToFrame’s oframe/pframe path and oriented with the path, false if it has opposed orientation, and nullopt if it is not fully contained in the path.

Parameters:

sub_f_to_f – the sub-path FrameToFrame’s orientation to check

Returns:

null if not on path, and true if on the path and oriented

const km::HomTran &relTransform() const#

Get the relative homogeneous transformation between the oframe and pframe.

The actual work is done by the transform cache callback, and this is a simple public wrapper for it.

Returns:

The homogeneous transformation.

const km::SpatialVector &relSpVel() const#

Get the relative velocity between the oframe and pframe.

This is the spatial velocity of the pframe with respect to the oframe, as observed from the oframe, and represented in the oframe.

The resulting linear velocity, o_v(o,p) is the derivative of o_l(o,p) vector, i.e. the time derivative of the oframe coordinate representation of the oframe/pframe translational vector. The actual work is done by the velocity cache callback, and this is a simple public wrapper for it.

Returns:

The spatial velocity vector.

km::Vec6 oframeDerivRelRates() const#

Return the transform rates for the oframe to pframe relative velocity.

This method converts the spatial velocity of the pframe with respect to the oframe, into the minimal coordinate rates 6-vector for the relative transform. The minimal coordinates are the Karana::Math::RotationVector representation of the attitude part, and the relative position of the linear part.

Returns:

The coordinate rates as a 6-vector

const km::SpatialVector &relSpAccel() const#

Get the relative acceleration between the oframe and pframe.

This is the spatial acceleration of the pframe with respect to the oframe, as observed from the oframe, and represented in the oframe.

The resulting linear accel, o_a(o,p) is the derivative of o_v(o,p) velocity, i.e. the time derivative of the oframe coordinate representation of the o_v(o,p) oframe/pframe translational velocity. The actual work is done by the accel cache callback, and this is a simple public wrapper for it.

Returns:

The spatial acceleration vector.

km::SpatialVector pframeObservedRelSpVel() const#

Return the pframe observed relative spatial velocity between the oframe and pframe.

This is the spatial velocity of the pframe with respect to the oframe, as observed from the pframe, and represented in the pframe.

The resulting linear velocity, p_v(o,p) is the derivative of p_l(o,p) = p_R_o * o_l(o,p) vector, i.e. the time derivative of the pframe coordinate representation of the oframe/pframe translational vector. Thus 

 p_v(o,p) = p_R_o * [ o_v(o,p) + o_l(o,p) x w(o,p) ]

Note that the returned value is NOT p_v(p,o) that corresponds to f_to_f(pframe, oframe).relSpVel() where the roles of oframe and pframe are switched, and the value would be the velocity of oframe with respect to pframe.

Returns:

The pframe observed spatial velocity vector.

km::SpatialVector pframeObservedRelSpAccel() const#

Return the pframe observed relative spatial acceleration between the oframe and pframe.

This is the spatial acceleration of the pframe with respect to the oframe, as observed from the pframe, and represented in pframe.

The resulting linear accel, p_a(o,p) is the derivative of p_R_o * o_v(o,p) vector, i.e. the time derivative of the pframe coordinate representation of the o_v(o,p) oframe/pframe translational velocity. 

 p_a(o,p) = p_R_o * [ o_a(o,p) + o_v(o,p) x w(o,p) ]

Note that the returned value is NOT p_a(p,o), which corresponds to f_to_f(pframe, oframe).relSpAccel(). To get p_a(p,o) you need to switch the roles of oframe and pframe and simply call pframe.relSpAccel(oframe).

Returns:

The pframe observed spatial acceleration vector.

const km::SpatialVector toPframeRelativeSpVel(const km::SpatialVector &oframe_v) const#

Transform the hypothetical oframe deriv relative spatial velocity into pframe relative value.

For this f_to_f, convert the hypothetical oframe derivative relative spatial velocity for the f_to_f into the corresponding pframe relative spatial velocity, i.e the derivative of the reversed pframe to the oframe vector quantities as observed from the pframe, and representing in the pframe. Thus this is computing B_alpha(B,A) from A_alpha(A,

B). This method assumes that the relative transform for the f_to_f is valid and uses it.

Note that when the hypothetical input oframe relative spatial velocity is the true value we will have the following equivalence:

toPframeRelativeSpVel(relSpVel()) == pframe()->frameToFrame(oframe())->relSpVel()

Note that this method changes the velocity vector from being oframe/pframe to being pframe/oframe, and thus is doing more than just changing the observing frame./

This method is handy for state initialization, where we are trying to initialize the multibody velocity coordinates based on some physical requirements on body/node spatial velocities. This method can be use to convert these requirements into requirements on the relative spatial velocities for the hinge, and at which point the hinge fitU() method can be used to compute the U velocity coordinates for the hinge that meet the requirements.

Parameters:

oframe_v – the hypothetical oframe relative spatial velocity

Returns:

the corresponding pframe relative spatial velocity

const km::SpatialVector toPframeRelativeSpAccel(const km::SpatialVector &oframe_a) const#

Transform the provided oframe relative spatial accel into pframe relative value.

For this f_to_f, convert the hypothetical oframe relative spatial accel for the f_to_f into the corresponding pframe relative spatial accel as if we are taking the derivative of the pframe to the oframe vector quantities as observed from the pframe, and represented in the pframe. This method assumes that the relative transform and spatial velocity for the f_to_f are valid and uses them.

Note that when the hypothetical input spatial accel is the true value we will have the following equivalence:

toPframeRelativeSpAccel(relSpAccel()) == pframe()->frameToFrame(oframe())->relSpAccel()

Note that this method changes the acceleration vector from being oframe/pframe to being pframe/oframe, and thus is doing more than just changing the observing frame./

This method is handy for multibody state initialization, where we are trying to initialize the multibody acceleration coordinates based on some physical requirements on body/node spatial acceleration. This method can be use to convert these requirements into requirements on the relative spatial acceleration on hinges, and at which point the hinge fitUdot() method can be used to compute the Udot acceleration coordinates for the hinge that meet the requirements.

Parameters:

oframe_a – the hypothetical oframe relative spatial accel

Returns:

the corresponding pframe relative spatial accel

const km::Vec3 toOframeObserved(const km::Vec3 &pframe_x, const km::Vec3 &pframe_x_dot) const#

Transform the 3-vector pframe observed derivative to oframe observed derivative.

This method converts the pframe observed time derivative of a 3-vector into the oframe observed time derivative.

Usage: This method is used to change the observing frame for a 3-vector derivative to a new one. To do this, create a f_to_f FrameToFrame from the new observing frame to the original observing frame for the vector derivative, and pass in the vector, x, and its time derivative, xdot, as arguments to f_to_f.toOframeObserved(x, xdot). The returned value will be the time derivative vector in the new observing frame.

Parameters:

  • pframe_x – the pframe representation of the 3-vector whose time derivative is being taken

  • pframe_x_dot – the (original) pframe observed time derivative of pframe_x

Returns:

the (new) oframe observed time derivative of pframe_x

km::Mat66 phiDotMatrix() const#

Get the time derivative of phi(oframe, pframe)

See The phi rigid body transformation matrix “rigid body transformation matrix” for a definition of the transformation matrix.

\[ \dot\phi(o, p) = -\phi(o, p) [\tilde V_o(o, p)]^* \]

See also

Karana::Math::HomTran::phi(), Karana::Math::HomTran::phiStar()

Returns:

phi time derivative matrix.

inline const kc::ks_ptr<kc::DataCache<km::HomTran>> &transformCache() const#

Return the transform data cache.

Returns:

the transform DataCache

inline const kc::ks_ptr<kc::DataCache<km::SpatialVector>> &velocityCache() const#

Return the velocity data cache.

Returns:

the velocity DataCache

inline const kc::ks_ptr<kc::DataCache<km::SpatialVector>> &accelCache() const#

Return the acceleration data cache.

Returns:

the acceleration DataCache

km::SpatialVector coriolisAccelOop(const Frame &target, const FrameToFrame &p_to_t_f_to_f) const#

Compute the ‘oop’ version of the Coriolis acceleration as defined above.

The result is expressed in oframe. The expression is from Exercise 1.14 (Spatial acceleration transformations), Eq 1.69. The returned value is in the ‘o’ from frame. 

     a_oop =    |             w(o,p) x w(p,t)          |
                |                                      |
                |  w(o,p) x [v(o, t) - v(o,p) + v(p,t] |

While not strictly necessary, we are passing the additional f_to_f arguments to avoid the costs of frame to frame lookups.

Parameters:

  • target – the target Frame

  • p_to_t_f_to_f – the pframe to target frame2frame

Returns:

the ‘oop’ Coriolis spatial acceleration vector

km::SpatialVector coriolisAccelTpp(const Frame &target, const FrameToFrame &p_to_t_f_to_f, const FrameToFrame &o_to_t_f_to_f) const#

Compute the ‘tpp’ version of the Coriolis acceleration as defined above.

The result is expressed in the target frame. The expression is from Exercise 1.14 (Spatial acceleration transformations), Eq 1.73. The returned value is in the ‘t’ target frame. 

     a_tpp =    |             w(o,p) x w(p,t)           |
                |                                       |
                |  w(o,p) x v(p, t)  + v(o,t) x w(p,t]  |

While not strictly necessary, we are passing the additional f_to_f arguments to avoid the costs of frame to frame lookups.

Parameters:

  • target – the target Frame

  • p_to_t_f_to_f – the pframe to target frame2frame

  • o_to_t_f_to_f – the oframe to target frame2frame

Returns:

the ‘tpp’ Coriolis spatial acceleration vector

km::HomTran solveTransform(const FrameToFrame &sub_f_to_f, const km::HomTran &T) const#

Solve for sub f_to_f’s transform needed to achieve desired relative transform.

Denoting this as the A/C f_to_f, and the desired relative transform as desired_T, this method solves for the relative transform required of the sub_f_to_f (which is assumed to be in the A/C path). It is required that sub_f_to_f be at one end or the other of the A/C f_to_f, i.e. it’s oframe is A, or that its pframe is C.

Parameters:

  • sub_f_to_f – the sub f_to_f whose required transform is to be computed

  • T – the desired relative transform for this f_to_f

Returns:

the relative transform required for the sub f_to_f

km::SpatialVector solveSpVel(const FrameToFrame &sub_f_to_f, const FrameToFrame &other_f_to_f, const km::SpatialVector &V) const#

Solve for sub f_to_f’s relative spatial velocity needed to achieve desired relative spatial velocity.

Denoting this as the A/C f_to_f, and the desired relative spatial velocity as V, this method solves for the relative spatial velocity required of the sub_f_to_f (which is assumed to be in the A/C path). It is required that sub_f_to_f be at one end or the other of the A/C f_to_f, i.e. it’s oframe is A, or that its pframe is C. The sub_f_to_f thus splits the A/C f_to_f path in two parts. The other_f_to_f is the f_to_f for the remaining half.

We pass in extra f_to_f’s to avoid the cost of lookups within this method.

Parameters:

  • sub_f_to_f – the sub f_to_f whose required spatial velocity is to be computed

  • other_f_to_f – the f_to_f for the segment of oframe/pframe not covered by sub_f_to_f

  • V – the desired relative spatial velocity for this f_to_f

Returns:

the relative spatial velocity required for the sub f_to_f

km::SpatialVector solveSpAccel(const FrameToFrame &sub_f_to_f, const FrameToFrame &other_f_to_f, const km::SpatialVector &A) const#

Solve for sub f_to_f’s relative spatial acceleration needed to achieve desired relative spatial acceleration.

Denoting this as the A/C f_to_f, and the desired relative spatial acceleration as A, this method solves for the relative spatial acceleration required of the sub_f_to_f (which is assumed to be in the A/C path). It is required that sub_f_to_f be at one end or the other of the A/C f_to_f, i.e. it’s oframe is A, or that its pframe is C. The sub_f_to_f thus splits the A/C f_to_f path in two parts. The other_f_to_f is the f_to_f for the remaining half.

We pass in extra f_to_f’s to avoid the cost of lookups within this method.

Parameters:

  • sub_f_to_f – the sub f_to_f whose required spatial acceleration is to be computed

  • other_f_to_f – the f_to_f for the segment of oframe/pframe not covered by sub_f_to_f

  • A – the desired relative spatial acceleration for this f_to_f

Returns:

the relative spatial acceleration required for the sub f_to_f

std::string dumpString(std::string_view prefix = "", const Base::DumpOptions *options = nullptr) const override#

Return a formatted string containing information about this object.

Parameters:

  • prefix – String prefix to use for formatting.

  • options – Dump options (if null, defaults will be used).

Returns:

A string representation of the object.

void freezeDataCaches()#

Freeze all data caches.

void unfreezeDataCaches()#

Unfreeze all data caches.

Protected Functions

FrameToFrame(const kc::ks_ptr<Frame> &oframe, const kc::ks_ptr<Frame> &pframe, std::string_view name = "")#

Constructor for FrameToFrame.

Parameters:

  • oframe – oframe of the FrameToFrame.

  • pframe – pframe of the FrameToFrame.

  • name – The name to use for the frame to frame. If none is supplied (the default), then an automatically derived name will be used.

virtual void _empty()#

Empty out the FrameToFrame completely. This happens when the oframe or pframe associated with the FrameToFrame is deleted.

virtual void _makeHealthy() override#

Make this FrameToFrame healthy.

virtual void _computeTransform(km::HomTran &T) = 0#

Compute the transformation between the oframe and pframe.

This the relTransform data cache callback.

Parameters:

T – The buffer to place the computed homogeneous transformation in.

virtual void _computeVelocity(km::SpatialVector &V) = 0#

Compute the spatial velocity between the oframe and pframe.

This the relSpVel data cache callback.

Parameters:

V – The buffer to put the computed spatial velocity in.

virtual void _computeAccel(km::SpatialVector &a) = 0#

Compute the spatial acceleration between the oframe and pframe.

This the relSpAccel data cache callback.

Parameters:

a – The buffer to put the computed spatial acceleration in.

km::SpatialVector _propagateVelocity_oop(const Frame &target, const FrameToFrame &p_to_t_f_to_f, const FrameToFrame &o_to_t_f_to_f) const#

Propagate spatial velocity from this oframe/pframe pair to a target frame.

This method combines the relSpVel values of 2 connected segments A/B and B/C to derive the overall A/C relSpVel value. The resulting derivatives are in the oframe, and the result is expressed in the oframe.

The expression is covered in Eq. 1.48 in Exercise 1.8 (Evaluating spatial velocities.)

V(A, C) = phistar(B, C) * V(A, B) + V(B, C)

While not strictly necessary, we are passing the additional f_to_f arguments to avoid the costs of frame to frame lookups.

Parameters:

  • target – The target frame.

  • p_to_t_f_to_f – the pframe to target frameToFrame.

  • o_to_t_f_to_f – the oframe to target frameToFrame.

Returns:

The combination of the oframe/pframe velocity with the pframe/target velocity.

km::SpatialVector _propagateAccel_oop(const Frame &target, const FrameToFrame &p_to_t_f_to_f, const FrameToFrame &o_to_t_f_to_f) const#

Propagate spatial acceleration from this oframe/pframe pair to a target frame.

This method combines the relSpAccel values of 2 connected segments A/B and B/C to derive the overall A/C relSpAccel value. The resulting derivatives are in the oframe, and the result is expressed in the oframe.

The expression is covered in Eq 1.74 in Exercise 1.15 (Evaluating spatial accelerations.). This includes the expression for the Coriolis term. The coriolisAccel_oop() method is used to compute the Coriolis acceleration for this case.

\[ \alpha(A, C) = phistar(B, C) * \alpha(A, B) + \alpha(B, C) + \text{Coriolis accel} \]

While not strictly necessary, we are passing the additional f_to_f arguments to avoid the costs of frame to frame lookups.

Parameters:

  • target – The target frame.

  • p_to_t_f_to_f – the pframe to target FrameToFrame.

  • o_to_t_f_to_f – the oframe to target FrameToFrame.

Returns:

The overall oframe/target spatial acceleration.

Protected Attributes

kc::ks_ptr<kc::DataCache<km::HomTran>> _transform_cache#

Cache for the homogeneous transform.

kc::ks_ptr<kc::DataCache<km::SpatialVector>> _velocity_cache#

Cache for the spatial velocity.

kc::ks_ptr<kc::DataCache<km::SpatialVector>> _accel_cache#

Cache for the spatial acceleration.

kc::ks_ptr<Frame> _oframe#

The oframe of the FrameToFrame.

kc::ks_ptr<Frame> _pframe#

The pframe of the FrameToFrame.

Protected Static Functions

static std::string _mkName(const Frame &oframe, const Frame &pframe, std::string_view suffix)#

Create a name for a FrameToFrame with the given oframe and pframe.

Parameters:

  • oframe – The oframe of the FrameToFrame.

  • pframe – The pframe of the FrameToFrame

  • suffix – The suffix to use in the name.

Returns:

The name for the FrameToFrame.

struct DumpOptions : public LockingBase::DumpOptions#

Options struct for the dumpString() method

Subclassed by Karana::Frame::OrientedChainedFrameToFrame::DumpOptions

Public Functions

DumpOptions() = default#
inline DumpOptions &operator=(const DumpOptions &p)#

Copy assignment operator.

Parameters:

p – DumpOptions to copy from.

Returns:

A reference to the assigned DumpOptions.

Public Members

unsigned int depth = 1#

The depth of nested objects to include (0 is all, 1 is one deep etc.)

bool data = true#

Report data values and cache status.

Contents