Drake
SpatialForce< T > Class Template Reference

Detailed Description

template<typename T>
class drake::multibody::SpatialForce< T >

This class is used to represent a spatial force (also called a wrench) that combines both rotational (torque) and translational force components.

Spatial forces are 6-element quantities that are pairs of ordinary 3-vectors. Elements 0-2 are the torque component while elements 3-5 are the force component. Both vectors must be expressed in the same frame, and the translational force is applied to a particular point of a body, but neither the frame nor the point are stored with a SpatialForce object; they must be understood from context. It is the responsibility of the user to keep track of the application point and the expressed-in frame. That is best accomplished through disciplined notation. In source code we use monogram notation where capital F is used to designate a spatial force quantity. We write a point P fixed to body (or frame) B as \(B_P\) which appears in code and comments as Bp. Then we write a particular spatial force as F_Bp_E where the _E suffix indicates that the expressed-in frame is E. This symbol represents a torque applied to body B, and a force applied to point P on B, with both vectors expressed in E. Very often the application point will be the body origin Bo; if no point is shown the origin is understood, so F_B_E means F_Bo_E. For a more detailed introduction on spatial vectors and the monogram notation please refer to section Spatial Vectors.

Template Parameters
TThe scalar type, which must be one of the default scalars.

#include <drake/multibody/math/spatial_force.h>

Public Member Functions

 SpatialForce ()
 Default constructor. More...
 
 SpatialForce (const Eigen::Ref< const Vector3< T >> &tau, const Eigen::Ref< const Vector3< T >> &f)
 SpatialForce constructor from a torque tau and a force f. More...
 
template<typename Derived >
 SpatialForce (const Eigen::MatrixBase< Derived > &F)
 SpatialForce constructor from an Eigen expression that represents a six-dimensional vector. More...
 
SpatialForce< T > & ShiftInPlace (const Vector3< T > &p_BpBq_E)
 In-place shift of a SpatialForce from one application point to another. More...
 
SpatialForce< T > Shift (const Vector3< T > &p_BpBq_E) const
 Shift of a SpatialForce from one application point to another. More...
 
dot (const SpatialVelocity< T > &V_IBp_E) const
 Given this spatial force F_Bp_E applied at point P of body B and expressed in a frame E, this method computes the 6-dimensional dot product with the spatial velocity V_IBp_E of body B at point P, measured in an inertial frame I and expressed in the same frame E in which the spatial force is expressed. More...
 
Implements CopyConstructible, CopyAssignable, MoveConstructible, MoveAssignable
 SpatialForce (const SpatialForce &)=default
 
SpatialForceoperator= (const SpatialForce &)=default
 
 SpatialForce (SpatialForce &&)=default
 
SpatialForceoperator= (SpatialForce &&)=default
 
- Public Member Functions inherited from SpatialVector< SpatialForce, T >
 SpatialVector ()
 Default constructor. More...
 
 SpatialVector (const Eigen::Ref< const Vector3< T >> &w, const Eigen::Ref< const Vector3< T >> &v)
 SpatialVector constructor from an rotational component w and a linear component v. More...
 
 SpatialVector (const Eigen::MatrixBase< OtherDerived > &V)
 SpatialVector constructor from an Eigen expression that represents a six-dimensional vector. More...
 
int size () const
 The total size of the concatenation of the angular and linear components. More...
 
const T & operator[] (int i) const
 Const access to the i-th component of this spatial vector. More...
 
T & operator[] (int i)
 Mutable access to the i-th component of this spatial vector. More...
 
const Vector3< T > & rotational () const
 Const access to the rotational component of this spatial vector. More...
 
Vector3< T > & rotational ()
 Mutable access to the rotational component of this spatial vector. More...
 
const Vector3< T > & translational () const
 Const access to the translational component of this spatial vector. More...
 
Vector3< T > & translational ()
 Mutable access to the translational component of this spatial vector. More...
 
const T * data () const
 Returns a (const) bare pointer to the underlying data. More...
 
T * mutable_data ()
 Returns a (mutable) bare pointer to the underlying data. More...
 
std::tuple< const T, const T > GetMaximumAbsoluteDifferences (const SpatialQuantity &other) const
 Returns the maximum absolute values of the differences in the rotational and translational components of this and other (i.e., the infinity norms of the difference in rotational and translational components). More...
 
decltype(T()< T()) IsNearlyEqualWithinAbsoluteTolerance (const SpatialQuantity &other, double rotational_tolerance, double translational_tolerance) const
 Compares the rotational and translational parts of this and other to check if they are the same to within specified absolute differences. More...
 
decltype(T()< T()) IsApprox (const SpatialQuantity &other, double tolerance=std::numeric_limits< double >::epsilon()) const
 Compares this spatial vector to the provided spatial vector other within a specified tolerance. More...
 
void SetNaN ()
 Sets all entries in this SpatialVector to NaN. More...
 
SpatialQuantitySetZero ()
 Sets both rotational and translational components of this SpatialVector to zero. More...
 
CoeffsEigenTypeget_coeffs ()
 Returns a reference to the underlying storage. More...
 
const CoeffsEigenTypeget_coeffs () const
 Returns a constant reference to the underlying storage. More...
 
SpatialQuantity operator- () const
 Unary minus operator. More...
 
SpatialQuantityoperator+= (const SpatialQuantity &V)
 Addition assignment operator. More...
 
SpatialQuantityoperator-= (const SpatialQuantity &V)
 Subtraction assignment operator. More...
 
SpatialQuantityoperator *= (const T &s)
 Multiplication assignment operator. More...
 
 SpatialVector (const SpatialVector &)=default
 
 SpatialVector (SpatialVector &&)=default
 
SpatialVectoroperator= (const SpatialVector &)=default
 
SpatialVectoroperator= (SpatialVector &&)=default
 

Static Public Member Functions

static void ShiftInPlace (EigenPtr< Matrix6X< T >> F_Bp_E_all, const Vector3< T > &p_BpBq_E)
 Performs a rigid in-place shift of each column of 6 x n matrix F_Bp_E_all as if each column were a SpatialForce. More...
 
static void Shift (const Eigen::Ref< const Matrix6X< T >> &F_Bp_E_all, const Vector3< T > &p_BpBq_E, EigenPtr< Matrix6X< T >> F_Bq_E_all)
 Performs a rigid shift of each column of 6 x n matrix F_Bp_E_all into F_Bq_E_all as if each column were a SpatialForce. More...
 
- Static Public Member Functions inherited from SpatialVector< SpatialForce, T >
static SpatialQuantity Zero ()
 Factory to create a zero SpatialVector, i.e. More...
 

Related Functions

(Note that these are not member functions.)

template<typename T >
SpatialForce< T > operator+ (const SpatialForce< T > &F1_Sp_E, const SpatialForce< T > &F2_Sp_E)
 Computes the resultant spatial force as the addition of two spatial forces F1_Sp_E and F2_Sp_E on a same system or body S, at the same point P and expressed in the same frame E. More...
 
template<typename T >
SpatialForce< T > operator- (const SpatialForce< T > &F1_Sp_E, const SpatialForce< T > &F2_Sp_E)
 Subtracts spatial force F2_Sp_E from F1_Sp_E. More...
 

Additional Inherited Members

- Public Types inherited from SpatialVector< SpatialForce, T >
enum  
 Sizes for spatial quantities and its components in three dimensions. More...
 
using SpatialQuantity = SpatialForce< T >
 The more specialized spatial vector class templated on the scalar type T. More...
 
using CoeffsEigenType = Vector6< T >
 The type of the underlying in-memory representation using an Eigen vector. More...
 

Constructor & Destructor Documentation

◆ SpatialForce() [1/5]

SpatialForce ( const SpatialForce< T > &  )
default

◆ SpatialForce() [2/5]

SpatialForce ( SpatialForce< T > &&  )
default

◆ SpatialForce() [3/5]

Default constructor.

In Release builds the elements of the newly constructed spatial force are left uninitialized resulting in a zero cost operation. However in Debug builds those entries are set to NaN so that operations using this uninitialized spatial force fail fast, allowing fast bug detection.

◆ SpatialForce() [4/5]

SpatialForce ( const Eigen::Ref< const Vector3< T >> &  tau,
const Eigen::Ref< const Vector3< T >> &  f 
)

SpatialForce constructor from a torque tau and a force f.

◆ SpatialForce() [5/5]

SpatialForce ( const Eigen::MatrixBase< Derived > &  F)
explicit

SpatialForce constructor from an Eigen expression that represents a six-dimensional vector.

This constructor will assert the size of F is six (6) at compile-time for fixed sized Eigen expressions and at run-time for dynamic sized Eigen expressions.

Member Function Documentation

◆ dot()

T dot ( const SpatialVelocity< T > &  V_IBp_E) const

Given this spatial force F_Bp_E applied at point P of body B and expressed in a frame E, this method computes the 6-dimensional dot product with the spatial velocity V_IBp_E of body B at point P, measured in an inertial frame I and expressed in the same frame E in which the spatial force is expressed.

This dot-product represents the power generated by this spatial force when its body and application point have the given spatial velocity. Although the two spatial vectors must be expressed in the same frame, the result is independent of that frame.

Warning
The result of this method cannot be interpreted as power unless the spatial velocity is measured in an inertial frame I.

◆ operator=() [1/2]

SpatialForce& operator= ( SpatialForce< T > &&  )
default

◆ operator=() [2/2]

SpatialForce& operator= ( const SpatialForce< T > &  )
default

◆ Shift() [1/2]

SpatialForce<T> Shift ( const Vector3< T > &  p_BpBq_E) const

Shift of a SpatialForce from one application point to another.

This is an alternate signature for shifting a spatial force's application point that does not change the original object. See ShiftInPlace() for more information.

Parameters
[in]p_BpBq_EShift vector from point P of body B to point Q of B, expressed in frame E. The "from" point Bp must be the current application point of this spatial force, and E must be the same expressed-in frame as for this spatial force.
Return values
F_Bq_EThe equivalent shifted spatial force, now applied at point Q rather than P.
See also
ShiftInPlace() to compute the shifted spatial force in-place modifying the original object.

◆ Shift() [2/2]

static void Shift ( const Eigen::Ref< const Matrix6X< T >> &  F_Bp_E_all,
const Vector3< T > &  p_BpBq_E,
EigenPtr< Matrix6X< T >>  F_Bq_E_all 
)
static

Performs a rigid shift of each column of 6 x n matrix F_Bp_E_all into F_Bq_E_all as if each column were a SpatialForce.

The spatial forces are assumed to be applied at point P of a body B, and we shift them to point Q of that body by modifying the moment appropriately (translational forces are unchanged). The first three elements of each column must store the torque (rotational) component while the last three elements store the force (translational) component. All quantities are expressed in the same common frame E.

Parameters
[in]F_Bp_E_allA 6 x n matrix of spatial forces at point Bp on input, shifted to point Bq on output.
[in]p_BpBq_EThe vector from point Bp to point Bq.
[out]F_Bq_E_allA 6 x n matrix of spatial forces shifted from Bp to Bq.
Precondition
Columns are spatial forces with torque first, then force.
F_Bq_E_all must be non-null and point to a 6 x n matrix (same size as the input matrix).
Note
Although this method will function if the input and output are the same matrix, it is faster to use ShiftInPlace() in that case since the translational components don't need to be copied.
See also
ShiftInPlace(const Vector3<T>&) for details.

◆ ShiftInPlace() [1/2]

SpatialForce<T>& ShiftInPlace ( const Vector3< T > &  p_BpBq_E)

In-place shift of a SpatialForce from one application point to another.

this spatial force F_Bp_E, which applies its translational force component to point P of body B, is modified to become the equivalent spatial force F_Bq_E that considers the force to be applied to point Q of body B instead (see class comment for more about this notation). This requires adjusting the torque component to account for the change in moment caused by the force shift.

We are given the vector from point P to point Q, as a position vector p_BpBq_E (or p_PQ_E) expressed in the same frame E as the spatial force. The operation performed, in coordinate-free form, is:

  τ_B  = τ_B -  p_BpBq x f_Bp
  f_Bq = f_Bp,  i.e. the force as applied to body B at Q is the
                same as was applied to B at P.

where τ and f represent the torque and force components respectively.

Notice this operation is linear. [Jain 2010], (§1.5, page 15) uses the "rigid body transformation operator" to write this as:

  F_Bq = Φ(p_BqBp)F_Bp = Φ(-p_BpBq)F_Bp

where Φ(p_PQ) is the linear operator:

  Φ(p_PQ) = | I₃ p_PQx |
            | 0     I₃ |

where p_PQx denotes the cross product, skew-symmetric, matrix such that p_PQx v = p_PQ x v. The transpose of this operator allow us to shift spatial velocities, see SpatialVelocity::Shift().

  • [Jain 2010] Jain, A., 2010. Robot and multibody dynamics: analysis and algorithms. Springer Science & Business Media, pp. 123-130.

For computation, all quantities above must be expressed in a common frame E; we add an _E suffix to each symbol to indicate that.

This operation is performed in-place modifying the original object.

Parameters
[in]p_BpBq_EShift vector from point P of body B to point Q of B, expressed in frame E. The "from" point Bp must be the current application point of this spatial force, and E must be the same expressed-in frame as for this spatial force.
Returns
A reference to this spatial force which is now F_Bq_E, that is, the force is now applied at point Q rather than P.
See also
Shift() to compute the shifted spatial force without modifying this original object.

◆ ShiftInPlace() [2/2]

static void ShiftInPlace ( EigenPtr< Matrix6X< T >>  F_Bp_E_all,
const Vector3< T > &  p_BpBq_E 
)
static

Performs a rigid in-place shift of each column of 6 x n matrix F_Bp_E_all as if each column were a SpatialForce.

The spatial forces are assumed to be applied at point P of a body B, and we shift them to point Q of that body by modifying the moment appropriately (translational forces are unchanged). Hence on output the matrix should be renamed F_Bq_E_all (conceptually). The first three elements of each column must store the torque (rotational) component while the last three elements store the force (translational) component. All quantities are expressed in the same common frame E.

Parameters
[in,out]F_Bp_E_allA 6 x n matrix of spatial forces at point Bp on input, shifted to point Bq on output.
[in]p_BpBq_EThe vector from point Bp to point Bq.
Precondition
Columns are spatial forces with torque first, then force.
See also
ShiftInPlace(const Vector3<T>&) for details.

Friends And Related Function Documentation

◆ operator+()

SpatialForce< T > operator+ ( const SpatialForce< T > &  F1_Sp_E,
const SpatialForce< T > &  F2_Sp_E 
)
related

Computes the resultant spatial force as the addition of two spatial forces F1_Sp_E and F2_Sp_E on a same system or body S, at the same point P and expressed in the same frame E.

Return values
Fr_Sp_EThe resultant spatial force on system or body S from combining F1_Sp_E and F2_Sp_E, applied at the same point P and in the same expressed-in frame E as the operand spatial forces.

◆ operator-()

SpatialForce< T > operator- ( const SpatialForce< T > &  F1_Sp_E,
const SpatialForce< T > &  F2_Sp_E 
)
related

Subtracts spatial force F2_Sp_E from F1_Sp_E.

Both spatial forces act on the same system or body S, at point P and are expressed in the same frame E.


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