Class Frame2Frame

Class Frame2Frame#

Nested Relationships#

Nested Types#

Inheritance Relationships#

Base Type#

Derived Types#

Class Documentation#

class Frame2Frame : public Karana::Core::LockingBase#

Represents a connection between two frames.

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

See The frames layer for more discussion on the frames layer.

Subclassed by Karana::Frame::ChainedFrame2Frame, Karana::Frame::EdgeFrame2Frame, Karana::Frame::OrientedChainedFrame2Frame

Public Functions

virtual ~Frame2Frame()#

Frame2Frame destructor.

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

Get the oframe of the Frame2Frame.

Returns:

oframe.

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

Get the pframe of the Frame2Frame.

Returns:

pframe.

std::optional<bool> subchainOrientation(const Frame2Frame &sub_f2f) const#

Check the relationship of a sub-chain f2f’s path wrt the overall f2f path.

Return true if the subh-chain f2f’s path is contained in the f2f’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_f2f – the sub-path Frame2Frame’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 wrt 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 wrt 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 postion 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 wrt 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 wrt 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 f2f(pframe, oframe).relSpVel() where the roles of oframe and pframe are switched, and the value would be the velocity of oframe wrt 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 wrt 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 f2f(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 toPframeDerivSpVel(const km::SpatialVector &oframe_V) const#

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

For this f2f, convert the candidate oframe derivate relative spatial velocity for the f2f into the relative spatial velocity as if we are taking the derivative of the pframe to the pframe vector quantities as observed from the pframe, and represented in the pframe. That is computing B_alpha(B,A) from A_alpha(A, B). This method assumes that the relative transform for the f2f is valid and uses it.

Note that toPframeDerivSpVel(relSpVel()) == pframe()->frame2Frame(oframe())->relSpVel()

This method is handy for state initialization, where we are trying to initialize the multibody velocity coordinates based on some physical reguirements 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 coordianates for the hinge that meet the requirements.

Parameters:

oframe_V – the candidate oframe derivate relative spatial velocity

Returns:

the corresponding pframe observed and represented spatial velocity

const km::SpatialVector toPframeDerivSpAccel(const km::SpatialVector &oframe_A) const#

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

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

Note that toPframeDerivSpAccel(relSpAccel()) == pframe()->frame2Frame(oframe())->relSpAccel()

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

Parameters:

oframe_A – the candidate oframe derivate relative spatial accel

Returns:

the corresponding pframe observed and represented spatial accel

const km::Vec3 toOframeObserved(const km::Vec3 &pframe_X, const km::Vec3 &pframe_Xdot) 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.

Application to change the observing frame for a 3-vector derivative: To do this, create a Frame2Frame from the new to the original observing frame for the vector derivative, and pass in the vector and its time derivative in the original observing frame as arguments. 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_Xdot – the pframe observed time derivative of pframe_X

Returns:

the oframe observed time derivative of pframe_X

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 coriolisAccel_oop(const Frame &target, const Frame2Frame &p2t_f2f) 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 f2f arguments to avoid the costs of frame to frame lookups.

Parameters:

  • target – the target Frame

  • p2t_f2f – the pframe to target frame2frame

Returns:

the ‘oop’ Coriolis spatial acceleration vector

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.

km::SpatialVector coriolisAccel_tpp(const Frame &target, const Frame2Frame &p2t_f2f, const Frame2Frame &o2t_f2f) 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 f2f arguments to avoid the costs of frame to frame lookups.

Parameters:

  • target – the target Frame

  • p2t_f2f – the pframe to target frame2frame

  • o2t_f2f – the oframe to target frame2frame

Returns:

the ‘tpp’ Coriolis spatial acceleration vector

km::HomTran solveTransform(const Frame2Frame &sub_f2f, const km::HomTran &desired_T) const#

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

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

Parameters:

  • sub_f2f – the sub f2f whose required transform is to be computed

  • desired_T – the desired relative transform for this f2f

Returns:

the relative transform required for the sub f2f

km::SpatialVector solveSpVel(const Frame2Frame &sub_f2f, const Frame2Frame &other_f2f, const km::SpatialVector &desired_V) const#

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

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

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

Parameters:

  • sub_f2f – the sub f2f whose required spatial velocity is to be computed

  • other_f2f – the f2f for the segment of oframe/pframe not covered by sub_f2f

  • desired_V – the desired relative spatial velocity for this f2f

Returns:

the relative spatial velocity required for the sub f2f

km::SpatialVector solveSpAccel(const Frame2Frame &sub_f2f, const Frame2Frame &other_f2f, const km::SpatialVector &desired_A) const#

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

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

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

Parameters:

  • sub_f2f – the sub f2f whose required spatial acceleration is to be computed

  • other_f2f – the f2f for the segment of oframe/pframe not covered by sub_f2f

  • desired_A – the desired relative spatial acceleration for this f2f

Returns:

the relative spatial acceleration required for the sub f2f

std::string dumpString(const std::string &prefix = "", const Base::dumpOptions *options = nullptr) const override#
void freezeDataCaches()#

Freeze all data caches.

void unfreezeDataCaches()#

Unfreeze all data caches.

virtual void makeZombie() override#

Make the frame2Frame a zombie. This removes references to the pnode and onde and ensures it cannot be made current anymore.

Protected Functions

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

Constructor for Frame2Frame.

Parameters:

  • name – suffix to include in auto-derived name

  • oframe – oframe of the f2f.

  • pframe – pframe of the f2f.

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

Compute the transformation between the oframe and pframe.

This the relTransform data cache callback.

Returns:

The computed homogeneous transformation.

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

Compute the spatial velocity between the oframe and pframe.

This the relSpVel data cache callback.

Returns:

The computed spatial velocity.

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

Compute the spatial acceleration between the oframe and pframe.

This the relSpAccel data cache callback.

Returns:

The computed spatial acceleration.

km::SpatialVector _propagateVelocity_oop(const Frame &target, const Frame2Frame &p2t_f2f, const Frame2Frame &o2t_f2f) 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 f2f arguments to avoid the costs of frame to frame lookups.

Parameters:

  • p2t_f2f – the pframe to target frame2frame

  • o2t_f2f – the oframe to target frame2frame

Returns:

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

km::SpatialVector _propagateAccel_oop(const Frame &target, const Frame2Frame &p2t_f2f, const Frame2Frame &o2t_f2f) 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 oframeDerivRelSpAcel 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) + coriolisaccel

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

Parameters:

  • p2t_f2f – the pframe to target frame2frame

  • o2t_f2f – the oframe to target frame2frame

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#
kc::ks_ptr<Frame> _pframe#

Protected Static Functions

static std::string _mkName(const Frame &oframe, const Frame &pframe, const std::string &suffix)#
struct dumpOptions : public LockingBase::dumpOptions#

Options struct for the dumpString() method

Subclassed by Karana::Frame::OrientedChainedFrame2Frame::dumpOptions

Public Functions

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

copy operator

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