Simbody  3.5

These utility functions are used for manipulation of spatial quantities that are contained in SpatialVec or SpatialMat objects. More...

Typedefs

typedef Vec< 2, Vec3 > SimTK::SpatialVec
 Spatial vectors are used for (rotation,translation) quantities and consist of a pair of Vec3 objects, arranged as a 2-vector of 3-vectors. More...
 
typedef Row< 2, Row3 > SimTK::SpatialRow
 This is the type of a transposed SpatialVec; it does not usually appear explicitly in user programs. More...
 
typedef Mat< 2, 2, Mat33 > SimTK::SpatialMat
 Spatial matrices are used to hold 6x6 matrices that are best viewed as 2x2 matrices of 3x3 matrices; most commonly for spatial and articulated body inertias and spatial shift matrices. More...
 

Functions

SpatialVec SimTK::findRelativeVelocity (const Transform &X_FA, const SpatialVec &V_FA, const Transform &X_FB, const SpatialVec &V_FB)
 Find the relative spatial velocity between two frames A and B whose individual spatial velocities are known with respect to a third frame F, with the result returned in A. More...
 
SpatialVec SimTK::findRelativeVelocityInF (const Vec3 &p_AB_F, const SpatialVec &V_FA, const SpatialVec &V_FB)
 Find the relative spatial velocity between two frames A and B whose individual spatial velocities are known in a third frame F, but leave the result in F. More...
 
SpatialVec SimTK::findRelativeAcceleration (const Transform &X_FA, const SpatialVec &V_FA, const SpatialVec &A_FA, const Transform &X_FB, const SpatialVec &V_FB, const SpatialVec &A_FB)
 Find the relative spatial acceleration between two frames A and B whose individual spatial accelerations are known with respect to a third frame F, with the result returned in A. More...
 
SpatialVec SimTK::findRelativeAccelerationInF (const Vec3 &p_AB_F, const SpatialVec &V_FA, const SpatialVec &A_FA, const SpatialVec &V_FB, const SpatialVec &A_FB)
 Find the relative spatial acceleration between two frames A and B whose individual spatial acceleration are known in a third frame F, but leave the result in F. More...
 
SpatialVec SimTK::reverseRelativeVelocity (const Transform &X_AB, const SpatialVec &V_AB)
 Given the relative velocity of frame B in frame A, reverse that to give the relative velocity of frame A in B. More...
 
SpatialVec SimTK::reverseRelativeVelocityInA (const Transform &X_AB, const SpatialVec &V_AB)
 Given the relative velocity of frame B in frame A, reverse that to give the relative velocity of frame A in B, but leave the result expressed in frame A. More...
 
SpatialVec SimTK::shiftVelocityBy (const SpatialVec &V_AB, const Vec3 &r_A)
 Shift a relative spatial velocity measured at some point to that same relative spatial quantity but measured at a new point given by an offset from the old one. More...
 
SpatialVec SimTK::shiftVelocityFromTo (const SpatialVec &V_A_BP, const Vec3 &fromP_A, const Vec3 &toQ_A)
 Shift a relative spatial velocity measured at some point P to that same relative spatial quantity but measured at a new point Q given the points P and Q. More...
 
SpatialVec SimTK::shiftForceBy (const SpatialVec &F_AP, const Vec3 &r_A)
 Shift a spatial force applied at some point of a body to that same spatial force applied at a new point given by an offset from the old one. More...
 
SpatialVec SimTK::shiftForceFromTo (const SpatialVec &F_AP, const Vec3 &fromP_A, const Vec3 &toQ_A)
 Shift a spatial force applied at some point P of a body to that same spatial force applied at a new point Q, given P and Q. More...
 
SpatialVec SimTK::shiftAccelerationBy (const SpatialVec &A_AB, const Vec3 &w_AB, const Vec3 &r_A)
 Shift a relative spatial acceleration measured at some point to that same relative spatial quantity but measured at a new point given by an offset from the old one. More...
 
SpatialVec SimTK::shiftAccelerationFromTo (const SpatialVec &A_A_BP, const Vec3 &w_AB, const Vec3 &fromP_A, const Vec3 &toQ_A)
 Shift a relative spatial acceleration measured at some point P to that same relative spatial quantity but measured at a new point Q given the points P and Q. More...
 

Detailed Description

These utility functions are used for manipulation of spatial quantities that are contained in SpatialVec or SpatialMat objects.

These are intended for expert use and are mostly used in the implemention of friendlier methods such as those in MobilizedBody that are used to obtain various spatial quantities.

Note
Although we use SpatialVec for both, there are two different spatial vector bases: one for motion quantities like velocities, accelerations, and momentum and another for forces and impulses; be sure to use the appropriate functions. Also, we use a pair of ordinary vectors, following Abhi Jain, rather than the similar but subtly different Plucker basis vectors used by Roy Featherstone.

Spatial vectors are used for combined (rotational,translational) quantities. These include

     spatial velocity     = (angularVelocity,linearVelocity)
     spatial acceleration = (angularAcceleration,linearAcceleration)
     spatial force        = (moment,force)

Spatial configuration (pose) has to be handled differently though since orientation is not a vector quantity. We use the Transform class for this concept, which includes an orientation matrix and a translation vector.

See also
Transform

Typedef Documentation

typedef Vec< 2, Vec3 > SimTK::SpatialVec

Spatial vectors are used for (rotation,translation) quantities and consist of a pair of Vec3 objects, arranged as a 2-vector of 3-vectors.

SpatialVec[0] is the rotational component; [1] is translational.

Quantities represented this way include

  • spatial velocity = (angularVelocity,linearVelocity)
  • spatial acceleration = (angularAcceleration,linearAcceleration)
  • generalized forces = (torque,force)

Spatial configuration has to be handled differently though since orientation is not a vector quantity. (We use Transform for this concept which includes a Rotation matrix and a translation Vec3.)

typedef Row< 2, Row3 > SimTK::SpatialRow

This is the type of a transposed SpatialVec; it does not usually appear explicitly in user programs.

This is the type of a transposed SpatialVec.

typedef Mat< 2, 2, Mat33 > SimTK::SpatialMat

Spatial matrices are used to hold 6x6 matrices that are best viewed as 2x2 matrices of 3x3 matrices; most commonly for spatial and articulated body inertias and spatial shift matrices.

This is used for primarily for spatial mass properties.

They also arise commonly as intermediates in computations involving SpatialVec objects.

Function Documentation

SpatialVec SimTK::findRelativeVelocity ( const Transform X_FA,
const SpatialVec V_FA,
const Transform X_FB,
const SpatialVec V_FB 
)
inline

Find the relative spatial velocity between two frames A and B whose individual spatial velocities are known with respect to a third frame F, with the result returned in A.

Parameters
[in]X_FAThe pose of frame A measured and expressed in frame F.
[in]V_FAThe spatial velocity of frame A measured and expressed in frame F.
[in]X_FBThe pose of frame B measured and expressed in frame F.
[in]V_FBThe spatial velocity of frame B measured and expressed in frame F.
Returns
V_AB, the relative spatial velocity of frame B in frame A, expressed in A.

Given the spatial velocity V_FA of frame A in a reference frame F, and the spatial velocity V_FB of frame B in F, and transforms giving the poses of frames A and B in F, calculate the relative velocity V_AB of frame B in frame A, measured and expressed in A. Typical usage:

Transform X_GA, X_GB; // assume these are known from somewhere
SpatialVec V_GA, V_GB;
SpatialVec V_AB = findRelativeVelocity(X_GA, V_GA,
X_GB, V_GB);
Note
This returns the result expressed in A which is almost always what you want; however, if you don't want it in that frame you can save 30 flops by calling findRelativeVelocityInF() instead.

Cost is 51 flops.

See also
findRelativeVelocityInF()
SpatialVec SimTK::findRelativeVelocityInF ( const Vec3 p_AB_F,
const SpatialVec V_FA,
const SpatialVec V_FB 
)
inline

Find the relative spatial velocity between two frames A and B whose individual spatial velocities are known in a third frame F, but leave the result in F.

Parameters
[in]p_AB_FThe vector from the A frame origin OA to the B frame origin OB, but expressed in frame F.
[in]V_FAThe spatial velocity of frame A measured and expressed in frame F.
[in]V_FBThe spatial velocity of frame B measured and expressed in frame F.
Returns
V_AB_F, the relative spatial velocity of frame B in frame A, but still expressed in F.

Typically the relative velocity of B in A would be returned in A; most users will want to use findRelativeVelocity() instead which returns the result in A. Use of this method saves the substantial cost of reexpressing the result, so is useful in the rare case that you don't want the final result in A. Example:

Transform X_GA, X_GB; // assume these are known from somewhere
SpatialVec V_GA, V_GB;
const Vec3 p_AB_G = X_GB.p() - X_GA.p();
SpatialVec V_AB_G = findRelativeVelocityInF(p_AB_G, V_GA, V_GB);

Cost is 18 flops.

See also
findRelativeVelocity()
SpatialVec SimTK::findRelativeAcceleration ( const Transform X_FA,
const SpatialVec V_FA,
const SpatialVec A_FA,
const Transform X_FB,
const SpatialVec V_FB,
const SpatialVec A_FB 
)
inline

Find the relative spatial acceleration between two frames A and B whose individual spatial accelerations are known with respect to a third frame F, with the result returned in A.

Parameters
[in]X_FAThe pose of frame A measured and expressed in frame F.
[in]V_FAThe spatial velocity of frame A measured and expressed in frame F.
[in]A_FAThe spatial acceleration of frame A measured and expressed in frame F.
[in]X_FBThe pose of frame B measured and expressed in frame F.
[in]V_FBThe spatial velocity of frame B measured and expressed in frame F.
[in]A_FBThe spatial acceleration of frame B measured and expressed in frame F.
Returns
A_AB, the relative spatial acceleration of frame B in frame A, expressed in A.

Given the spatial acceleration A_FA of frame A in a reference frame F, and the spatial acceleration A_FB of frame B in F, and corresonding pose and velocity information, calculate the relative acceleration A_AB of frame B in frame A, measured and expressed in A. Typical usage:

Transform X_GA, X_GB; // assume these are known from somewhere
SpatialVec V_GA, V_GB;
SpatialVec A_GA, A_GB;
SpatialVec A_AB = findRelativeAcceleration(X_GA, V_GA, A_GA,
X_GB, V_GB, A_GB);
Note
This returns the result expressed in A which is almost always what you want; however, if you don't want it in that frame you can save 30 flops by calling findRelativeAccelerationInF() instead.

Cost is 105 flops.

See also
findRelativeAccelerationInF()
SpatialVec SimTK::findRelativeAccelerationInF ( const Vec3 p_AB_F,
const SpatialVec V_FA,
const SpatialVec A_FA,
const SpatialVec V_FB,
const SpatialVec A_FB 
)
inline

Find the relative spatial acceleration between two frames A and B whose individual spatial acceleration are known in a third frame F, but leave the result in F.

Parameters
[in]p_AB_FThe vector from the A frame origin OA to the B frame origin OB, but expressed in frame F.
[in]V_FAThe spatial velocity of frame A measured and expressed in frame F.
[in]A_FAThe spatial acceleration of frame A measured and expressed in frame F.
[in]V_FBThe spatial velocity of frame B measured and expressed in frame F.
[in]A_FBThe spatial acceleration of frame B measured and expressed in frame F.
Returns
A_AB_F, the relative spatial acceleration of frame B in frame A, but still expressed in F.

Typically the relative acceleration of B in A would be returned in A; most users will want to use findRelativeAcceleration() instead which returns the result in A. Use of this method saves the substantial cost of reexpressing the result, so is useful in the rare case that you don't want the final result in A. Example:

Transform X_GA, X_GB; // assume these are known from somewhere
SpatialVec V_GA, V_GB;
SpatialVec A_GA, A_GB;
const Vec3 p_AB_G = X_GB.p() - X_GA.p();
SpatialVec A_AB_G = findRelativeAccelerationInF(p_AB_G, V_GA, A_GA,
V_GB, A_GB);

Cost is 72 flops.

See also
findRelativeAcceleration()
SpatialVec SimTK::reverseRelativeVelocity ( const Transform X_AB,
const SpatialVec V_AB 
)
inline

Given the relative velocity of frame B in frame A, reverse that to give the relative velocity of frame A in B.

Parameters
[in]X_ABThe pose of frame B in frame A, measured and expressed in A.
[in]V_ABThe relative spatial velocity of frame B in frame A, measured and expressed in frame A.
Returns
V_BA, the relative spatial velocity of frame A in frame B, measured and expressed in B.

The input is expressed in the A frame; the result will be expressed in the B frame instead. If you prefer that the result remain in the A frame you should call reverseRelativeVelocityInA() instead to avoid the extra cost of changing frames. Example:

Transform X_AB; // assume these are known from somewhere
Note
If the frame origins were in the same spatial location, then the result would just be the negative of the supplied velocity. However, since the linear component of spatial velocity has to be measured at a point, and we're switching from measuring at a point coincident with B's origin OB to one coincident with A's origin OA, there is going to be a change in the linear part of the result. The angular velocity will just be negated, though, and then reexpressed in B.

Cost is 51 flops.

See also
reverseRelativeVelocityInA()
SpatialVec SimTK::reverseRelativeVelocityInA ( const Transform X_AB,
const SpatialVec V_AB 
)
inline

Given the relative velocity of frame B in frame A, reverse that to give the relative velocity of frame A in B, but leave the result expressed in frame A.

Parameters
[in]X_ABThe pose of frame B in frame A, measured and expressed in A.
[in]V_ABThe relative spatial velocity of frame B in frame A, measured and expressed in frame A.
Returns
V_BA_A, the relative velocity of frame A in frame B, but still expressed in A.

The input V_AB is expressed in the A frame; you will almost always want the output V_BA expressed in the B frame which is what the function reverseRelativeVelocity() does. However, if you're going to want it in some other frame ultimately you may prefer to avoid the substantial cost of reexpressing it in B now, in which case this routine is useful.

See reverseRelativeVelocity() for more information about what this does. Example:

Transform X_AB; // assume these are known from somewhere
SpatialVec V_AB; // (expressed in A)
// result is still expressed in A

Cost is 21 flops.

See also
reverseRelativeVelocity()
SpatialVec SimTK::shiftVelocityBy ( const SpatialVec V_AB,
const Vec3 r_A 
)
inline

Shift a relative spatial velocity measured at some point to that same relative spatial quantity but measured at a new point given by an offset from the old one.

Parameters
[in]V_ABThe relative spatial velocity of frame B in frame A, measured and expressed in frame A.
[in]r_AThe vector offset, expressed in frame A, by which to change the point at which the translational component of the relative spatial velocity is measured.
Returns
V_A_BQ, the relative velocity of frame B in frame A, but measured at the point Q=Bo+r rather than at B's origin Bo.

Given the spatial velocity V_AB of frame B in A, measured at a point coincident with B's origin Bo, change it to the spatial velocity V_A_BQ representing the same relationship but with the velocity measured at a new point Q=Bo+r for some position vector r. All vectors are measured and expressed in frame A, including the vector r. Example:

SpatialVec V_AB; // assume these are known from somewhere
Vec3 offset_A; // Q = Bo + offset
SpatialVec V_A_BQ = shiftVelocityBy(V_AB, offset_A);
Note
The shift in location leaves the relative angular velocity w the same but results in the linear velocity changing by w X r.

Cost is 12 flops.

See also
shiftVelocityFromTo()
SpatialVec SimTK::shiftVelocityFromTo ( const SpatialVec V_A_BP,
const Vec3 fromP_A,
const Vec3 toQ_A 
)
inline

Shift a relative spatial velocity measured at some point P to that same relative spatial quantity but measured at a new point Q given the points P and Q.

Parameters
[in]V_A_BPThe relative spatial velocity of frame B in frame A, measured and expressed in frame A, with the linear component measured at a point P.
[in]fromP_AThe "from" point P at which the input linear velocity was measured, given as a vector from A's origin OA to the point P, expressed in A.
[in]toQ_AThe "to" point Q at which we want to re-measure the linear velocity, given as a vector from A's origin OA to the point Q, expressed in A.
Returns
V_A_BQ, the relative velocity of frame B in frame A, but measured at the point Q rather than at point P.

Given the spatial velocity V_A_BP of frame B in A, measured at a point P, change it to the spatial velocity V_A_BQ representing the same relationship but with the velocity measured at a new point Q. Example:

// assume these are known from somewhere
Transform X_AB; // contains the vector from OA to OB
SpatialVec V_AB; // linear velocity is measured at origin OB of B
Vec3 p_AQ; // vector from OA to some other point Q, in A
SpatialVec V_A_BQ = shiftVelocityFromTo(V_AB, X_AB.p(), p_AQ);
Note
There is no way to know whether the supplied velocity was actually measured at P; this method really just shifts the relative velocity by the vector r=(to-from). Use it carefully.

Cost is 15 flops.

See also
shiftVelocityBy()
SpatialVec SimTK::shiftForceBy ( const SpatialVec F_AP,
const Vec3 r_A 
)
inline

Shift a spatial force applied at some point of a body to that same spatial force applied at a new point given by an offset from the old one.

Parameters
[in]F_APA spatial force (moment and linear force), expressed in the A frame, whose translational component is applied at a point P.
[in]r_AThe vector offset, expressed in frame A, by which to change the point at which the translational component of the input force is to be applied.
Returns
F_AQ, the same physical effect as the input but with the moment adjusted to reflect force application at point Q=P+r rather than at the original point P.

Given the spatial force F_AP including a pure moment m and a force vector f applied at a point P, return the equivalent force F_AQ representing the same physical quantity but as though the force were applied at a point Q=P+r for some position vector r. All vectors are expressed in frame A. Example:

SpatialVec F_AP; // assume these are known from somewhere
Vec3 offset_A; // Q = P + offset
SpatialVec F_AQ = shiftForceBy(F_AP, offset_A);
Note
The shift in location leaves the force f the same but results in an adjustment to the moment of -(r X f).

Cost is 12 flops.

See also
shiftForceFromTo()
SpatialVec SimTK::shiftForceFromTo ( const SpatialVec F_AP,
const Vec3 fromP_A,
const Vec3 toQ_A 
)
inline

Shift a spatial force applied at some point P of a body to that same spatial force applied at a new point Q, given P and Q.

Parameters
[in]F_APA spatial force (moment and linear force), expressed in the A frame, whose translational component is applied at a point P.
[in]fromP_AThe "from" point P at which the input force is applied, given as a vector from A's origin OA to the point P, expressed in A.
[in]toQ_AThe "to" point Q to which we want to move the force application point, given as a vector from A's origin OA to the point Q, expressed in A.
Returns
F_AQ, the same physical effect as the input but with the moment adjusted to reflect force application at point Q rather than at the original point P.

Given the spatial force F_AP including a pure moment m and a force vector f applied at a point P, return the equivalent force F_AQ representing the same physical quantity but as though the force were applied at a new point Q. All vectors are expressed in frame A and points are measured from A's origin OA. Example:

// assume these are known from somewhere
SpatialVec F_AP; // linear force is applied at point P
Vec3 p_AP; // vector from OA to P, in A
Vec3 p_AQ; // vector from OA to some other point Q, in A
SpatialVec F_AQ = shiftForceFromTo(F_AP, p_AP, p_AQ);
Note
There is no way to know whether the supplied force was actually applied at P; this method really just shifts the application point by the vector r=(to-from). Use it carefully.

Cost is 15 flops.

See also
shiftForceBy()
SpatialVec SimTK::shiftAccelerationBy ( const SpatialVec A_AB,
const Vec3 w_AB,
const Vec3 r_A 
)
inline

Shift a relative spatial acceleration measured at some point to that same relative spatial quantity but measured at a new point given by an offset from the old one.

Parameters
[in]A_ABThe relative spatial acceleration of frame B in frame A, measured and expressed in frame A.
[in]w_ABThe relative angular velocity of frame B in frame A, expressed in frame A.
[in]r_AThe vector offset, expressed in frame A, by which to change the point at which the translational component of the relative spatial acceleration is measured.
Returns
A_A_BQ, the relative acceleration of frame B in frame A, but measured at the point Q=Bo+r rather than at B's origin Bo.

Given the spatial acceleration A_AB and angular velocity w_AB of frame B in A, measured at a point coincident with B's origin Bo, change it to the spatial acceleration A_A_BQ representing the same relationship but with the acceleration measured at a new point Q=Bo+r for some position vector r. All vectors are measured and expressed in frame A, including the vector r. Example:

SpatialVec A_AB; // assume these are known from somewhere
Vec3 w_AB;
Vec3 offset_A; // Q = Bo + offset
SpatialVec A_A_BQ = shiftAccelerationBy(A_AB, w_AB, offset_A);
Note
The shift in location leaves the relative angular acceleration b the same but results in the linear acceleration changing by b X r + w X (w X r).

Cost is 33 flops.

See also
shiftAccelerationFromTo()
SpatialVec SimTK::shiftAccelerationFromTo ( const SpatialVec A_A_BP,
const Vec3 w_AB,
const Vec3 fromP_A,
const Vec3 toQ_A 
)
inline

Shift a relative spatial acceleration measured at some point P to that same relative spatial quantity but measured at a new point Q given the points P and Q.

Parameters
[in]A_A_BPThe relative spatial acceleration of frame B in frame A, measured and expressed in frame A, with the linear component measured at a point P.
[in]w_ABThe relative angular velocity of frame B in frame A, expressed in frame A.
[in]fromP_AThe "from" point P at which the input linear acceleration was measured, given as a vector from A's origin Ao to the point P, expressed in A.
[in]toQ_AThe "to" point Q at which we want to re-measure the linear acceleration, given as a vector from A's origin Ao to the point Q, expressed in A.
Returns
A_A_BQ, the relative acceleration of frame B in frame A, but measured at the point Q rather than at point P.

Given the spatial acceleration A_A_BP of frame B in A, measured at a point P, change it to the spatial acceleration A_A_BQ representing the same relationship but with the acceleration measured at a new point Q. Example:

// assume these are known from somewhere
Transform X_AB; // contains the vector from Ao to Bo
SpatialVec A_AB; // linear acceleration is measured at origin Bo of B
Vec3 w_AB;
Vec3 p_AQ; // vector from Ao to some other point Q, in A
SpatialVec A_A_BQ = shiftAccelerationFromTo(A_AB, w_AB, X_AB.p(), p_AQ);
Note
There is no way to know whether the supplied acceleration was actually measured at P; this method really just shifts the relative acceleration by the vector r=(to-from). Use it carefully.

Cost is 36 flops.

See also
shiftAccelerationBy()