Simbody  3.5
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Modules Pages
SimTK::Transform_< P > Class Template Reference

This class represents the rotate-and-shift transform which gives the location and orientation of a new frame F in a base (reference) frame B. More...

Public Member Functions

 Transform_ ()
 Default constructor gives an identity transform. More...
 
 Transform_ (const Rotation_< P > &R, const Vec< 3, P > &p)
 Combine a rotation and a translation into a transform. More...
 
 Transform_ (const Rotation_< P > &R)
 Construct or default-convert a rotation into a transform containing that rotation and zero translation. More...
 
 Transform_ (const Vec< 3, P > &p)
 Construct or default-convert a translation (expressed as a Vec3) into a transform with that translation and a zero rotation. More...
 
Transform_operator= (const InverseTransform_< P > &X)
 Assignment from InverseTransform. More...
 
template<int S>
Transform_operator+= (const Vec< 3, P, S > &offset_B)
 Add an offset to the position vector in this Transform. More...
 
template<int S>
Transform_operator-= (const Vec< 3, P, S > &offset_B)
 Subtract an offset from the position vector in this Transform. More...
 
Transform_set (const Rotation_< P > &R, const Vec< 3, P > &p)
 Assign a new value to this transform, explicitly providing the rotation and translation separately. More...
 
Transform_setToZero ()
 By zero we mean "zero transform", i.e., an identity rotation and zero translation. More...
 
Transform_setToNaN ()
 This fills both the rotation and translation with NaNs. More...
 
const InverseTransform_< P > & invert () const
 Return a read-only inverse of the current Transform_. More...
 
InverseTransform_< P > & updInvert ()
 Return a writable (lvalue) inverse of the current transform, simply by casting it to the InverseTransform_. More...
 
const InverseTransform_< P > & operator~ () const
 Overload transpose operator to mean inversion. More...
 
InverseTransform_< P > & operator~ ()
 Overload transpose operator to mean inversion. More...
 
Transform_ compose (const Transform_ &X_FY) const
 Compose the current transform (X_BF) with the given one. More...
 
Transform_ compose (const InverseTransform_< P > &X_FY) const
 Compose the current transform (X_BF) with one that is supplied as an InverseTransform_ (typically as a result of applying the "~" operator to a transform). More...
 
Vec< 3, P > xformFrameVecToBase (const Vec< 3, P > &vF) const
 Transform a vector expressed in our "F" frame to our "B" frame. More...
 
Vec< 3, P > xformBaseVecToFrame (const Vec< 3, P > &vB) const
 Transform a vector expressed in our "B" frame to our "F" frame. More...
 
Vec< 3, P > shiftFrameStationToBase (const Vec< 3, P > &sF) const
 Transform a point (station) measured from and expressed in our "F" frame to that same point but measured from and expressed in our "B" frame. More...
 
Vec< 3, P > shiftBaseStationToFrame (const Vec< 3, P > &sB) const
 Transform a point (station) measured from and expressed in our "B" frame to that same point but measured from and expressed in our "F" frame. More...
 
const Rotation_< P > & R () const
 Return a read-only reference to the contained rotation R_BF. More...
 
Rotation_< P > & updR ()
 Return a writable (lvalue) reference to the contained rotation R_BF. More...
 
const Rotation_< P >::ColType & x () const
 Return a read-only reference to the x direction (unit vector) of the F frame, expressed in the B frame. More...
 
const Rotation_< P >::ColType & y () const
 Return a read-only reference to the y direction (unit vector) of the F frame, expressed in the B frame. More...
 
const Rotation_< P >::ColType & z () const
 Return a read-only reference to the z direction (unit vector) of the F frame, expressed in the B frame. More...
 
const InverseRotation_< P > & RInv () const
 Return a read-only reference to the inverse (transpose) of our contained rotation, that is R_FB. More...
 
InverseRotation_< P > & updRInv ()
 Return a writable (lvalue) reference to the inverse (transpose) of our contained rotation, that is R_FB. More...
 
const Vec< 3, P > & p () const
 Return a read-only reference to our translation vector p_BF. More...
 
Vec< 3, P > & updP ()
 Return a writable (lvalue) reference to our translation vector p_BF. More...
 
Transform_< P > & setP (const Vec< 3, P > &p)
 Assign a new value to our translation vector. More...
 
Vec< 3, P > pInv () const
 Calculate the inverse of the translation vector in this transform. More...
 
Transform_< P > & setPInv (const Vec< 3, P > &p_FB)
 Assign a value to the inverse of our translation vector. More...
 
const Mat< 3, 4, P > & asMat34 () const
 Recast this transform as a read-only 3x4 matrix. More...
 
Mat< 3, 4, P > toMat34 () const
 Less efficient version of asMat34(); copies into return variable. More...
 
Mat< 4, 4, P > toMat44 () const
 Return the equivalent 4x4 transformation matrix. More...
 
const Vec< 3, P > & T () const
 
Vec< 3, P > & updT ()
 

Related Functions

(Note that these are not member functions.)

template<class P , int S>
Vec< 3, P > operator* (const Transform_< P > &X_BF, const Vec< 3, P, S > &s_F)
 If we multiply a transform or inverse transform by a 3-vector, we treat the vector as though it had a 4th element "1" appended, that is, it is treated as a station rather than a vector. More...
 
template<class P , int S>
Transform_< P > operator+ (const Transform_< P > &X_BF, const Vec< 3, P, S > &offset_B)
 Adding a 3-vector to a Transform produces a new shifted transform. More...
 
template<class P , int S>
Transform_< P > operator+ (const Vec< 3, P, S > &offset_B, const Transform_< P > &X_BF)
 Adding a 3-vector to a Transform produces a new shifted transform. More...
 
template<class P , int S>
Transform_< P > operator- (const Transform_< P > &X_BF, const Vec< 3, P, S > &offset_B)
 Subtracting a 3-vector from a Transform produces a new shifted transform. More...
 
template<class P , int S>
Vec< 4, P > operator* (const Transform_< P > &X_BF, const Vec< 4, P, S > &a_F)
 If we multiply a transform or inverse transform by an augmented 4-vector, we use the 4th element to decide how to treat it. More...
 
template<class P , class E >
Vector_< Eoperator* (const Transform_< P > &X, const VectorBase< E > &v)
 Multiplying a matrix or vector by a Transform_. More...
 
template<class P >
Transform_< P > operator* (const Transform_< P > &X1, const Transform_< P > &X2)
 Composition of transforms. More...
 
template<class P >
bool operator== (const Transform_< P > &X1, const Transform_< P > &X2)
 Comparison operators return true only if the two transforms are bit identical; that's not too useful. More...
 
template<class P >
std::ostream & operator<< (std::ostream &, const Transform_< P > &)
 Generate formatted output of a Transform to an output stream. More...
 

Detailed Description

template<class P>
class SimTK::Transform_< P >

This class represents the rotate-and-shift transform which gives the location and orientation of a new frame F in a base (reference) frame B.

A frame is an orthogonal, right-handed set of three axes, and an origin point. A transform X from frame B to F consists of 3 perpendicular unit vectors defining F's axes as viewed from B (that is, as expressed in the basis formed by B's axes), and a vector from B's origin point Bo to F's origin point Fo. Note that the meaning of "B" comes from the context in which the transform is used. We use the phrase "frame F is in frame B" to describe the above relationship, that is, "in" means both measured from and expressed in.

The axis vectors constitute a Rotation_. They are ordered 1-2-3 or x-y-z as you prefer, with z = x X y, making a right-handed set. These axes are arranged as columns of a 3x3 rotation matrix R_BF = [ x y z ] which is a direction cosine (rotation) matrix useful for conversions between frame B and F. (The columns of R_BF are F's coordinate axes, expressed in B.) For example, given a vector vF expressed in the F frame, that same vector re-expressed in B is given by vB = R_BF*vF. F's origin point OF is stored as the translation vector p_BF=(Fo-Bo) and expressed in B.

Transform is designed to behave as much as possible like the computer graphics 4x4 affine transform X which would be arranged like this:

        [       |   ]
    X = [   R   | p ]    R is a 3x3 orthogonal rotation matrix
        [.......|...]    p is a 3x1 translation vector
        [ 0 0 0   1 ]

These can be composed directly by matrix multiplication, but more importantly they have a particularly simple inverse:

   -1   [       |    ]
  X   = [  ~R   | p* ]   ~R is R transpose, p* = ~R(-p).
        [.......|....]
        [ 0 0 0   1  ] 

This inverse is so simple that we compute it simply by defining another type, InverseTransform_, which is identical to Transform_ in memory but behaves as though it contains the inverse. That way we invert just by changing point of view (recasting) rather than computing.

This is a "POD" (plain old data) class with a well-defined memory layout on which a client of this class may depend: There are exactly 4 consecutive, packed 3-vectors in the order x,y,z,p. That is, this class is equivalent to an array of 12 Reals with the order x1,x2,x3,y1,y2,y3,z1,z2,z3,p1,p2,p3. It is expressly allowed to reinterpret Transform objects in any appropriate manner that depends on this memory layout.

Constructor & Destructor Documentation

template<class P>
SimTK::Transform_< P >::Transform_ ( )
inline

Default constructor gives an identity transform.

template<class P>
SimTK::Transform_< P >::Transform_ ( const Rotation_< P > &  R,
const Vec< 3, P > &  p 
)
inline

Combine a rotation and a translation into a transform.

template<class P>
SimTK::Transform_< P >::Transform_ ( const Rotation_< P > &  R)
inline

Construct or default-convert a rotation into a transform containing that rotation and zero translation.

template<class P>
SimTK::Transform_< P >::Transform_ ( const Vec< 3, P > &  p)
inline

Construct or default-convert a translation (expressed as a Vec3) into a transform with that translation and a zero rotation.

Member Function Documentation

template<class P>
Transform_< P > & SimTK::Transform_< P >::operator= ( const InverseTransform_< P > &  X)
inline

Assignment from InverseTransform.

This means that the transform we're assigning to must end up with the same meaning as the inverse transform X has, so we'll need to end up with:

  • p == X.p()
  • R == X.R()

Cost: one frame conversion and a negation, 18 flops.

template<class P>
template<int S>
Transform_& SimTK::Transform_< P >::operator+= ( const Vec< 3, P, S > &  offset_B)
inline

Add an offset to the position vector in this Transform.

Cost is 3 flops.

template<class P>
template<int S>
Transform_& SimTK::Transform_< P >::operator-= ( const Vec< 3, P, S > &  offset_B)
inline

Subtract an offset from the position vector in this Transform.

Cost is 3 flops.

template<class P>
Transform_& SimTK::Transform_< P >::set ( const Rotation_< P > &  R,
const Vec< 3, P > &  p 
)
inline

Assign a new value to this transform, explicitly providing the rotation and translation separately.

We return a reference to the now-modified transform as though this were an assignment operator.

template<class P>
Transform_& SimTK::Transform_< P >::setToZero ( )
inline

By zero we mean "zero transform", i.e., an identity rotation and zero translation.

We return a reference to the now-modified transform as though this were an assignment operator.

template<class P>
Transform_& SimTK::Transform_< P >::setToNaN ( )
inline

This fills both the rotation and translation with NaNs.

Note: this is not the same as a default-constructed transform, which is a legitimate identity transform instead. We return a reference to the now-modified transform as though this were an assignment operator.

template<class P>
const InverseTransform_<P>& SimTK::Transform_< P >::invert ( ) const
inline

Return a read-only inverse of the current Transform_.

, simply by casting it to the InverseTransform_

type. Zero cost.

template<class P>
InverseTransform_<P>& SimTK::Transform_< P >::updInvert ( )
inline

Return a writable (lvalue) inverse of the current transform, simply by casting it to the InverseTransform_.

type. That is, this is an lvalue. Zero cost.

template<class P>
const InverseTransform_<P>& SimTK::Transform_< P >::operator~ ( ) const
inline

Overload transpose operator to mean inversion.

See also
invert
template<class P>
InverseTransform_<P>& SimTK::Transform_< P >::operator~ ( )
inline

Overload transpose operator to mean inversion.

See also
updInvert
template<class P>
Transform_ SimTK::Transform_< P >::compose ( const Transform_< P > &  X_FY) const
inline

Compose the current transform (X_BF) with the given one.

That is, return X_BY=X_BF*X_FY. Cost is 63 flops.

template<class P>
Transform_< P > SimTK::Transform_< P >::compose ( const InverseTransform_< P > &  X_FY) const
inline

Compose the current transform (X_BF) with one that is supplied as an InverseTransform_ (typically as a result of applying the "~" operator to a transform).

That is, return X_BY=X_BF*X_FY, but now X_FY is represented as ~X_YF. Cost is an extra 18 flops to calculate X_FY.p(), total 81 flops.

template<class P>
Vec<3,P> SimTK::Transform_< P >::xformFrameVecToBase ( const Vec< 3, P > &  vF) const
inline

Transform a vector expressed in our "F" frame to our "B" frame.

Note that this involves rotation only; it is independent of the translation stored in this transform. Cost is 15 flops.

template<class P>
Vec<3,P> SimTK::Transform_< P >::xformBaseVecToFrame ( const Vec< 3, P > &  vB) const
inline

Transform a vector expressed in our "B" frame to our "F" frame.

Note that this involves rotation only; it is independent of the translation stored in this transform. Cost is 15 flops.

template<class P>
Vec<3,P> SimTK::Transform_< P >::shiftFrameStationToBase ( const Vec< 3, P > &  sF) const
inline

Transform a point (station) measured from and expressed in our "F" frame to that same point but measured from and expressed in our "B" frame.

Cost is 18 flops.

template<class P>
Vec<3,P> SimTK::Transform_< P >::shiftBaseStationToFrame ( const Vec< 3, P > &  sB) const
inline

Transform a point (station) measured from and expressed in our "B" frame to that same point but measured from and expressed in our "F" frame.

Cost is 18 flops.

template<class P>
const Rotation_<P>& SimTK::Transform_< P >::R ( ) const
inline

Return a read-only reference to the contained rotation R_BF.

template<class P>
Rotation_<P>& SimTK::Transform_< P >::updR ( )
inline

Return a writable (lvalue) reference to the contained rotation R_BF.

template<class P>
const Rotation_<P>::ColType& SimTK::Transform_< P >::x ( ) const
inline

Return a read-only reference to the x direction (unit vector) of the F frame, expressed in the B frame.

template<class P>
const Rotation_<P>::ColType& SimTK::Transform_< P >::y ( ) const
inline

Return a read-only reference to the y direction (unit vector) of the F frame, expressed in the B frame.

template<class P>
const Rotation_<P>::ColType& SimTK::Transform_< P >::z ( ) const
inline

Return a read-only reference to the z direction (unit vector) of the F frame, expressed in the B frame.

template<class P>
const InverseRotation_<P>& SimTK::Transform_< P >::RInv ( ) const
inline

Return a read-only reference to the inverse (transpose) of our contained rotation, that is R_FB.

template<class P>
InverseRotation_<P>& SimTK::Transform_< P >::updRInv ( )
inline

Return a writable (lvalue) reference to the inverse (transpose) of our contained rotation, that is R_FB.

template<class P>
const Vec<3,P>& SimTK::Transform_< P >::p ( ) const
inline

Return a read-only reference to our translation vector p_BF.

template<class P>
Vec<3,P>& SimTK::Transform_< P >::updP ( )
inline

Return a writable (lvalue) reference to our translation vector p_BF.

Caution: if you write through this reference you update the transform.

template<class P>
Transform_<P>& SimTK::Transform_< P >::setP ( const Vec< 3, P > &  p)
inline

Assign a new value to our translation vector.

We expect the supplied vector p to be expressed in our B frame. A reference to the now-modified transform is returned as though this were an assignment operator.

template<class P>
Vec<3,P> SimTK::Transform_< P >::pInv ( ) const
inline

Calculate the inverse of the translation vector in this transform.

The returned vector will be the negative of the original and will be expressed in the F frame rather than our B frame. Cost is 18 flops.

template<class P>
Transform_<P>& SimTK::Transform_< P >::setPInv ( const Vec< 3, P > &  p_FB)
inline

Assign a value to the inverse of our translation vector.

That is, we're given a vector in F which we invert and reexpress in B to store it in p, so that we get the original argument back if we ask for the inverse of p. Sorry, can't update pInv as an lvalue, but here we want -(~R_BF*p_BF)=p_FB => p_BF=-(R_BF*p_FB) so we can calculate it in 18 flops. A reference to the now-modified transform is returned as though this were an assignment operator.

template<class P>
const Mat<3,4,P>& SimTK::Transform_< P >::asMat34 ( ) const
inline

Recast this transform as a read-only 3x4 matrix.

This is a zero-cost reinterpretation of the data; the first three columns are the columns of the rotation and the last column is the translation.

template<class P>
Mat<3,4,P> SimTK::Transform_< P >::toMat34 ( ) const
inline

Less efficient version of asMat34(); copies into return variable.

template<class P>
Mat<4,4,P> SimTK::Transform_< P >::toMat44 ( ) const
inline

Return the equivalent 4x4 transformation matrix.

template<class P>
const Vec<3,P>& SimTK::Transform_< P >::T ( ) const
inline
template<class P>
Vec<3,P>& SimTK::Transform_< P >::updT ( )
inline

Friends And Related Function Documentation

template<class P , int S>
Vec< 3, P > operator* ( const Transform_< P > &  X_BF,
const Vec< 3, P, S > &  s_F 
)
related

If we multiply a transform or inverse transform by a 3-vector, we treat the vector as though it had a 4th element "1" appended, that is, it is treated as a station rather than a vector.

This way we use both the rotational and translational components of the transform.

template<class P , int S>
Transform_< P > operator+ ( const Transform_< P > &  X_BF,
const Vec< 3, P, S > &  offset_B 
)
related

Adding a 3-vector to a Transform produces a new shifted transform.

template<class P , int S>
Transform_< P > operator+ ( const Vec< 3, P, S > &  offset_B,
const Transform_< P > &  X_BF 
)
related

Adding a 3-vector to a Transform produces a new shifted transform.

template<class P , int S>
Transform_< P > operator- ( const Transform_< P > &  X_BF,
const Vec< 3, P, S > &  offset_B 
)
related

Subtracting a 3-vector from a Transform produces a new shifted transform.

template<class P , int S>
Vec< 4, P > operator* ( const Transform_< P > &  X_BF,
const Vec< 4, P, S > &  a_F 
)
related

If we multiply a transform or inverse transform by an augmented 4-vector, we use the 4th element to decide how to treat it.

The 4th element must be 0 or 1. If 0 it is treated as a vector only and the translation is ignored. If 1 it is treated as a station and rotated & shifted.

template<class P , class E >
Vector_< E > operator* ( const Transform_< P > &  X,
const VectorBase< E > &  v 
)
related

Multiplying a matrix or vector by a Transform_.

applies it to each element individually.

template<class P >
Transform_< P > operator* ( const Transform_< P > &  X1,
const Transform_< P > &  X2 
)
related

Composition of transforms.

Operators are provided for all the combinations of transform and inverse transform.

template<class P >
bool operator== ( const Transform_< P > &  X1,
const Transform_< P > &  X2 
)
related

Comparison operators return true only if the two transforms are bit identical; that's not too useful.

template<class P >
std::ostream & operator<< ( std::ostream &  ,
const Transform_< P > &   
)
related

Generate formatted output of a Transform to an output stream.


The documentation for this class was generated from the following file: