Detailed Description

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

Body provides the general abstraction of a body with an API that makes no assumption about whether a body is rigid or deformable and neither does it make any assumptions about the underlying physical model or approximation.

As an element or component of a MultibodyPlant, a body is a MultibodyElement, and therefore it has a unique index of type BodyIndex within the multibody plant it belongs to.

A Body contains a unique BodyFrame; see BodyFrame class documentation for more information.

Template Parameters

T	The scalar type, which must be one of the default scalars.

#include <drake/multibody/tree/revolute_spring.h>

Public Member Functions
BodyIndex	index () const
	Returns this element's unique index. More...

const std::string &	name () const
	Gets the `name` associated with `this` body. The name will never be empty. More...

ScopedName	scoped_name () const
	Returns scoped name of this frame. More...

const BodyFrame< T > &	body_frame () const
	Returns a const reference to the associated BodyFrame. More...

void	Lock (systems::Context< T > *context) const
	For a floating body, lock its inboard joint. More...

void	Unlock (systems::Context< T > *context) const
	For a floating body, unlock its inboard joint. More...

bool	is_locked (const systems::Context< T > &context) const
	Determines whether this Body is currently locked to its inboard (parent) Body. More...

internal::MobodIndex	mobod_index () const
	(Advanced) Returns the index of the mobilized body ("mobod") in the computational directed forest structure of the owning MultibodyTree to which this Body belongs. More...

internal::MobodIndex	node_index () const
	(Deprecated.) More...

bool	is_floating () const
	(Advanced) Returns `true` if `this` body is granted 6-dofs by a Mobilizer and the parent body of this body's associated 6-dof joint is `world`. More...

bool	has_quaternion_dofs () const
	(Advanced) If `true`, this body's generalized position coordinates q include a quaternion, which occupies the first four elements of q. More...

int	floating_positions_start () const
	(Advanced) For floating bodies (see is_floating()) this method returns the index of this Body's first generalized position in the vector q of generalized position coordinates for a MultibodyPlant model. More...

int	floating_velocities_start () const
	(Advanced, Deprecated) For floating bodies (see is_floating()) this method returns the index of this Body's first generalized velocity in the full state vector for a MultibodyPlant model, under the dubious assumption that the state consists of [q v] concatenated. More...

int	floating_velocities_start_in_v () const
	(Advanced) For floating bodies (see is_floating()) this method returns the index of this Body's first generalized velocity in the vector v of generalized velocities for a MultibodyPlant model. More...

std::string	floating_position_suffix (int position_index_in_body) const
	Returns a string suffix (e.g. More...

std::string	floating_velocity_suffix (int velocity_index_in_body) const
	Returns a string suffix (e.g. More...

virtual double	default_mass () const =0
	Returns the default mass (not Context dependent) for `this` body. More...

virtual RotationalInertia< double >	default_rotational_inertia () const =0
	Returns the default rotational inertia (not Context dependent) for `this` body B's about Bo (B's origin), expressed in B (this body's frame). More...

virtual const T &	get_mass (const systems::Context< T > &context) const =0
	(Advanced) Returns the mass of this body stored in `context`. More...

virtual const Vector3< T >	CalcCenterOfMassInBodyFrame (const systems::Context< T > &context) const =0
	(Advanced) Computes the center of mass `p_BoBcm_B` (or `p_Bcm` for short) of this body measured from this body's frame origin `Bo` and expressed in the body frame B. More...

virtual Vector3< T >	CalcCenterOfMassTranslationalVelocityInWorld (const systems::Context< T > &context) const =0
	Calculates v_WBcm, Bcm's translational velocity in the world frame W. More...

virtual SpatialInertia< T >	CalcSpatialInertiaInBodyFrame (const systems::Context< T > &context) const =0
	(Advanced) Computes the SpatialInertia `I_BBo_B` of `this` body about its frame origin `Bo` (not necessarily its center of mass) and expressed in its body frame `B`. More...

const math::RigidTransform< T > &	EvalPoseInWorld (const systems::Context< T > &context) const
	Returns the pose `X_WB` of this body B in the world frame W as a function of the state of the model stored in `context`. More...

const SpatialVelocity< T > &	EvalSpatialVelocityInWorld (const systems::Context< T > &context) const
	Evaluates V_WB, `this` body B's spatial velocity in the world frame W. More...

const SpatialAcceleration< T > &	EvalSpatialAccelerationInWorld (const systems::Context< T > &context) const
	Evaluates A_WB, `this` body B's spatial acceleration in the world frame W. More...

const SpatialForce< T > &	GetForceInWorld (const systems::Context< T > &, const MultibodyForces< T > &forces) const
	Gets the sptatial force on `this` body B from `forces` as F_BBo_W: applied at body B's origin Bo and expressed in world frame W. More...

void	AddInForceInWorld (const systems::Context< T > &, const SpatialForce< T > &F_Bo_W, MultibodyForces< T > *forces) const
	Adds the spatial force on `this` body B, applied at body B's origin Bo and expressed in the world frame W into `forces`. More...

void	AddInForce (const systems::Context< T > &context, const Vector3< T > &p_BP_E, const SpatialForce< T > &F_Bp_E, const Frame< T > &frame_E, MultibodyForces< T > *forces) const
	Adds the spatial force on `this` body B, applied at point P and expressed in a frame E into `forces`. More...

template<typename ToScalar >
std::unique_ptr< Body< ToScalar > >	CloneToScalar (const internal::MultibodyTree< ToScalar > &tree_clone) const
	NVI (Non-Virtual Interface) to DoCloneToScalar() templated on the scalar type of the new clone to be created. More...

Does not allow copy, move, or assignment
	Body (const Body &)=delete

Body &	operator= (const Body &)=delete

	Body (Body &&)=delete

Body &	operator= (Body &&)=delete

Public Member Functions inherited from MultibodyElement< T >
virtual	~MultibodyElement ()

ModelInstanceIndex	model_instance () const
	Returns the ModelInstanceIndex of the model instance to which this element belongs. More...

template<typename MultibodyPlantDeferred = MultibodyPlant<T>>
const MultibodyPlantDeferred &	GetParentPlant () const
	Returns the MultibodyPlant that owns this MultibodyElement. More...

void	DeclareParameters (internal::MultibodyTreeSystem< T > *tree_system)
	Declares MultibodyTreeSystem Parameters at MultibodyTreeSystem::Finalize() time. More...

void	SetDefaultParameters (systems::Parameters< T > *parameters) const
	Sets default values of parameters belonging to each MultibodyElement in `parameters` at a call to MultibodyTreeSystem::SetDefaultParameters(). More...

	MultibodyElement (const MultibodyElement &)=delete

MultibodyElement &	operator= (const MultibodyElement &)=delete

	MultibodyElement (MultibodyElement &&)=delete

MultibodyElement &	operator= (MultibodyElement &&)=delete

Protected Member Functions
	Body (const std::string &name, ModelInstanceIndex model_instance)
	Creates a Body named `name` in model instance `model_instance`. More...

virtual void	DoDeclareBodyParameters (internal::MultibodyTreeSystem< T > *)
	Called by DoDeclareParameters(). More...

virtual void	DoSetDefaultBodyParameters (systems::Parameters< T > *) const
	Called by DoSetDefaultParameters(). More...

Methods to make a clone templated on different scalar types.
These methods are meant to be called by MultibodyTree::CloneToScalar() when making a clone of the entire tree or a new instance templated on a different scalar type. The only const argument to these methods is the new MultibodyTree clone under construction. Specific Body subclasses might specify a number of prerequisites on the cloned tree and therefore require it to be at a given state of cloning (for instance requiring that the cloned tree already contains all the frames in the world as in the original tree.) See MultibodyTree::CloneToScalar() for a list of prerequisites that are guaranteed to be satisfied during the cloning process.
virtual std::unique_ptr< Body< double > >	DoCloneToScalar (const internal::MultibodyTree< double > &tree_clone) const =0
	Clones this Body (templated on T) to a body templated on `double`. More...

virtual std::unique_ptr< Body< AutoDiffXd > >	DoCloneToScalar (const internal::MultibodyTree< AutoDiffXd > &tree_clone) const =0
	Clones this Body (templated on T) to a body templated on AutoDiffXd. More...

virtual std::unique_ptr< Body< symbolic::Expression > >	DoCloneToScalar (const internal::MultibodyTree< symbolic::Expression > &) const =0
	Clones this Body (templated on T) to a body templated on Expression. More...

Protected Member Functions inherited from MultibodyElement< T >
	MultibodyElement ()
	Default constructor made protected so that sub-classes can still declare their default constructors if they need to. More...

	MultibodyElement (ModelInstanceIndex model_instance)
	Constructor which allows specifying a model instance. More...

template<typename ElementIndexType >
ElementIndexType	index_impl () const
	Returns this element's unique index. More...

const internal::MultibodyTree< T > &	get_parent_tree () const
	Returns a constant reference to the parent MultibodyTree that owns this element. More...

const internal::MultibodyTreeSystem< T > &	GetParentTreeSystem () const
	Returns a constant reference to the parent MultibodyTreeSystem that owns the parent MultibodyTree that owns this element. More...

void	SetTopology (const internal::MultibodyTreeTopology &tree)
	Gives MultibodyElement-derived objects the opportunity to retrieve their topology after MultibodyTree::Finalize() is invoked. More...

systems::NumericParameterIndex	DeclareNumericParameter (internal::MultibodyTreeSystem< T > *tree_system, const systems::BasicVector< T > &model_vector)
	To be used by MultibodyElement-derived objects when declaring parameters in their implementation of DoDeclareParameters(). More...

systems::AbstractParameterIndex	DeclareAbstractParameter (internal::MultibodyTreeSystem< T > *tree_system, const AbstractValue &model_value)
	To be used by MultibodyElement-derived objects when declaring parameters in their implementation of DoDeclareParameters(). More...

Friends
class	internal::BodyAttorney< T >

Constructor & Destructor Documentation

◆ Body() [1/3]

Body ( const Body< T > & )

delete

◆ Body() [2/3]

Body ( Body< T > && )

delete

◆ Body() [3/3]

Body	(	const std::string &	name,
		ModelInstanceIndex	model_instance
	)

protected

Creates a Body named name in model instance model_instance.

The name must not be empty.

Member Function Documentation

◆ AddInForce()

void AddInForce	(	const systems::Context< T > &	context,
		const Vector3< T > &	p_BP_E,
		const SpatialForce< T > &	F_Bp_E,
		const Frame< T > &	frame_E,
		MultibodyForces< T > *	forces
	)		const

Adds the spatial force on this body B, applied at point P and expressed in a frame E into forces.

Parameters

[in]	context	The context containing the current state of the model.
[in]	p_BP_E	The position of point P in B, expressed in a frame E.
[in]	F_Bp_E	The spatial force to be applied on body B at point P, expressed in frame E.
[in]	frame_E	The expressed-in frame E.
[out]	forces	A multibody forces objects that on output will have `F_Bp_E` added.

Exceptions

std::exception if forces is nullptr or if it is not consistent with the model to which this body belongs.

◆ AddInForceInWorld()

void AddInForceInWorld	(	const systems::Context< T > &	,
		const SpatialForce< T > &	F_Bo_W,
		MultibodyForces< T > *	forces
	)		const

Adds the spatial force on this body B, applied at body B's origin Bo and expressed in the world frame W into forces.

◆ body_frame()

const BodyFrame<T>& body_frame ( ) const

Returns a const reference to the associated BodyFrame.

◆ CalcCenterOfMassInBodyFrame()

virtual const Vector3<T> CalcCenterOfMassInBodyFrame ( const systems::Context< T > & context ) const

pure virtual

(Advanced) Computes the center of mass p_BoBcm_B (or p_Bcm for short) of this body measured from this body's frame origin Bo and expressed in the body frame B.

Implemented in RigidBody< T >.

◆ CalcCenterOfMassTranslationalVelocityInWorld()

virtual Vector3<T> CalcCenterOfMassTranslationalVelocityInWorld ( const systems::Context< T > & context ) const

pure virtual

Calculates v_WBcm, Bcm's translational velocity in the world frame W.

Parameters

[in] context The context contains the state of the model.

Return values

v_WBcm_W Bcm's (this body's center of mass) translational velocity in the world frame W, expressed in W.

Implemented in RigidBody< T >.

◆ CalcSpatialInertiaInBodyFrame()

virtual SpatialInertia<T> CalcSpatialInertiaInBodyFrame ( const systems::Context< T > & context ) const

pure virtual

(Advanced) Computes the SpatialInertia I_BBo_B of this body about its frame origin Bo (not necessarily its center of mass) and expressed in its body frame B.

The spatial inertia of a RigidBody in its body frame is constant, but may need to be calculated from Parameters.

Implemented in RigidBody< T >.

◆ CloneToScalar()

std::unique_ptr<Body<ToScalar> > CloneToScalar ( const internal::MultibodyTree< ToScalar > & tree_clone ) const

NVI (Non-Virtual Interface) to DoCloneToScalar() templated on the scalar type of the new clone to be created.

This method is mostly intended to be called by MultibodyTree::CloneToScalar(). Most users should not call this clone method directly but rather clone the entire parent MultibodyTree if needed.

See also: MultibodyTree::CloneToScalar()

◆ default_mass()

virtual double default_mass ( ) const

pure virtual

Returns the default mass (not Context dependent) for this body.

In general, a body's mass can be a Context-dependent parameter that is returned by the method get_mass(). When a body's mass is a parameter, the value returned by default_mass() is used to initialize the mass parameter in the Context.

Implemented in RigidBody< T >.

◆ default_rotational_inertia()

virtual RotationalInertia<double> default_rotational_inertia ( ) const

pure virtual

Returns the default rotational inertia (not Context dependent) for this body B's about Bo (B's origin), expressed in B (this body's frame).

Return values

I_BBo_B body B's rotational inertia about Bo, expressed in B.

Implemented in RigidBody< T >.

◆ DoCloneToScalar() [1/3]

virtual std::unique_ptr<Body<double> > DoCloneToScalar ( const internal::MultibodyTree< double > & tree_clone ) const

protectedpure virtual

Clones this Body (templated on T) to a body templated on double.

Implemented in RigidBody< T >.

◆ DoCloneToScalar() [2/3]

virtual std::unique_ptr<Body<AutoDiffXd> > DoCloneToScalar ( const internal::MultibodyTree< AutoDiffXd > & tree_clone ) const

protectedpure virtual

Clones this Body (templated on T) to a body templated on AutoDiffXd.

Implemented in RigidBody< T >.

◆ DoCloneToScalar() [3/3]

virtual std::unique_ptr<Body<symbolic::Expression> > DoCloneToScalar ( const internal::MultibodyTree< symbolic::Expression > & ) const

protectedpure virtual

Clones this Body (templated on T) to a body templated on Expression.

Implemented in RigidBody< T >.

◆ DoDeclareBodyParameters()

virtual void DoDeclareBodyParameters ( internal::MultibodyTreeSystem< T > * )

protectedvirtual

Called by DoDeclareParameters().

Derived classes may choose to override to declare their sub-class specific parameters.

Reimplemented in RigidBody< T >.

◆ DoSetDefaultBodyParameters()

virtual void DoSetDefaultBodyParameters ( systems::Parameters< T > * ) const

protectedvirtual

Called by DoSetDefaultParameters().

Derived classes may choose to override to set their sub-class specific parameters.

Reimplemented in RigidBody< T >.

◆ EvalPoseInWorld()

const math::RigidTransform<T>& EvalPoseInWorld ( const systems::Context< T > & context ) const

Returns the pose X_WB of this body B in the world frame W as a function of the state of the model stored in context.

◆ EvalSpatialAccelerationInWorld()

const SpatialAcceleration<T>& EvalSpatialAccelerationInWorld ( const systems::Context< T > & context ) const

Evaluates A_WB, this body B's spatial acceleration in the world frame W.

Parameters

[in] context Contains the state of the model.

Return values

A_WB_W this body B's spatial acceleration in the world frame W, expressed in W (for point Bo, the body's origin).

Note: When cached values are out of sync with the state stored in context, this method performs an expensive forward dynamics computation, whereas once evaluated, successive calls to this method are inexpensive.

◆ EvalSpatialVelocityInWorld()

const SpatialVelocity<T>& EvalSpatialVelocityInWorld ( const systems::Context< T > & context ) const

Evaluates V_WB, this body B's spatial velocity in the world frame W.

Parameters

[in] context Contains the state of the model.

Return values

V_WB_W this body B's spatial velocity in the world frame W, expressed in W (for point Bo, the body frame's origin).

◆ floating_position_suffix()

std::string floating_position_suffix ( int position_index_in_body ) const

Returns a string suffix (e.g.

to be appended to the name()) to identify the kth position in the floating base. position_index_in_body must be in [0, 7) if has_quaternion_dofs() is true, otherwise in [0, 6).

Exceptions

std::exception if called pre-finalize

Precondition: this is a floating body

See also: is_floating(), has_quaternion_dofs(), MultibodyPlant::Finalize()

◆ floating_positions_start()

int floating_positions_start ( ) const

(Advanced) For floating bodies (see is_floating()) this method returns the index of this Body's first generalized position in the vector q of generalized position coordinates for a MultibodyPlant model.

Positions q for this Body are then contiguous starting at this index. When a floating Body is modeled with quaternion coordinates (see has_quaternion_dofs()), the four consecutive entries in the state starting at this index correspond to the quaternion that parametrizes this Body's orientation.

Exceptions

std::exception if called pre-finalize

Precondition: this is a floating body

See also: is_floating(), has_quaternion_dofs(), MultibodyPlant::Finalize()

◆ floating_velocities_start()

int floating_velocities_start ( ) const

(Advanced, Deprecated) For floating bodies (see is_floating()) this method returns the index of this Body's first generalized velocity in the full state vector for a MultibodyPlant model, under the dubious assumption that the state consists of [q v] concatenated.

Velocities for this body are then contiguous starting at this index.

Exceptions

std::exception if called pre-finalize

Precondition: this is a floating body

See also: floating_velocities_start_in_v() (Deprecated.)

Deprecated:: Convert to floating_velocities_start_in_v(). In a state with [q v] concatenated, offset by num_positions() to get to the start of v.
This will be removed from Drake on or after 2024-02-01.

◆ floating_velocities_start_in_v()

int floating_velocities_start_in_v ( ) const

(Advanced) For floating bodies (see is_floating()) this method returns the index of this Body's first generalized velocity in the vector v of generalized velocities for a MultibodyPlant model.

Velocities v for this Body are then contiguous starting at this index.

Exceptions

std::exception if called pre-finalize

Precondition: this is a floating body

See also: is_floating(), MultibodyPlant::Finalize()

◆ floating_velocity_suffix()

std::string floating_velocity_suffix ( int velocity_index_in_body ) const

Returns a string suffix (e.g.

to be appended to the name()) to identify the kth velocity in the floating base. velocity_index_in_body must be in [0,6).

Exceptions

std::exception if called pre-finalize

Precondition: this is a floating body

See also: is_floating(), MultibodyPlant::Finalize()

◆ get_mass()

virtual const T& get_mass ( const systems::Context< T > & context ) const

pure virtual

(Advanced) Returns the mass of this body stored in context.

Implemented in RigidBody< T >.

◆ GetForceInWorld()

const SpatialForce<T>& GetForceInWorld	(	const systems::Context< T > &	,
		const MultibodyForces< T > &	forces
	)		const

Gets the sptatial force on this body B from forces as F_BBo_W: applied at body B's origin Bo and expressed in world frame W.

◆ has_quaternion_dofs()

bool has_quaternion_dofs ( ) const

(Advanced) If true, this body's generalized position coordinates q include a quaternion, which occupies the first four elements of q.

Note that this does not imply that the body is floating since it may have fewer than 6 dofs or its inboard body could be something other than World.

Exceptions

std::exception if called pre-finalize

See also: is_floating(), MultibodyPlant::Finalize()

◆ index()

BodyIndex index ( ) const

Returns this element's unique index.

◆ is_floating()

bool is_floating ( ) const

(Advanced) Returns true if this body is granted 6-dofs by a Mobilizer and the parent body of this body's associated 6-dof joint is world.

Note: A floating body is not necessarily modeled with a quaternion mobilizer, see has_quaternion_dofs(). Alternative options include a space XYZ parametrization of rotations, see SpaceXYZMobilizer.

Exceptions

std::exception if called pre-finalize,

See also: MultibodyPlant::Finalize()

◆ is_locked()

bool is_locked ( const systems::Context< T > & context ) const

Determines whether this Body is currently locked to its inboard (parent) Body.

This is not limited to floating bodies but generally Joint::is_locked() is preferable otherwise.

Returns: true if the body is locked, false otherwise.

◆ Lock()

void Lock ( systems::Context< T > * context ) const

For a floating body, lock its inboard joint.

Its generalized velocities will be 0 until it is unlocked.

Exceptions

std::exception if this body is not a floating body.

◆ mobod_index()

internal::MobodIndex mobod_index ( ) const

(Advanced) Returns the index of the mobilized body ("mobod") in the computational directed forest structure of the owning MultibodyTree to which this Body belongs.

This serves as the BodyNode index and the index into all associated quantities.

◆ name()

const std::string& name ( ) const

Gets the name associated with this body. The name will never be empty.

◆ node_index()

internal::MobodIndex node_index ( ) const

(Deprecated.)

Deprecated:: Use mobod_index() instead.
This will be removed from Drake on or after 2024-03-01.

◆ operator=() [1/2]

Body& operator= ( const Body< T > & )

delete

◆ operator=() [2/2]

Body& operator= ( Body< T > && )

delete

◆ scoped_name()

ScopedName scoped_name ( ) const

Returns scoped name of this frame.

Neither of the two pieces of the name will be empty (the scope name and the element name).

◆ Unlock()

void Unlock ( systems::Context< T > * context ) const

For a floating body, unlock its inboard joint.

Exceptions

std::exception if this body is not a floating body.

Friends And Related Function Documentation

◆ internal::BodyAttorney< T >

friend class internal::BodyAttorney< T >

friend

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

drake/multibody/tree/body.h

Detailed Description

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

Public Member Functions

Protected Member Functions

Friends

Constructor & Destructor Documentation

◆ Body() [1/3]

◆ Body() [2/3]

◆ Body() [3/3]

Member Function Documentation

◆ AddInForce()

◆ AddInForceInWorld()

◆ body_frame()

◆ CalcCenterOfMassInBodyFrame()

◆ CalcCenterOfMassTranslationalVelocityInWorld()

◆ CalcSpatialInertiaInBodyFrame()

◆ CloneToScalar()

◆ default_mass()

◆ default_rotational_inertia()

◆ DoCloneToScalar() [1/3]

◆ DoCloneToScalar() [2/3]

◆ DoCloneToScalar() [3/3]

◆ DoDeclareBodyParameters()

◆ DoSetDefaultBodyParameters()

◆ EvalPoseInWorld()

◆ EvalSpatialAccelerationInWorld()

◆ EvalSpatialVelocityInWorld()

◆ floating_position_suffix()

◆ floating_positions_start()

◆ floating_velocities_start()

◆ floating_velocities_start_in_v()

◆ floating_velocity_suffix()

◆ get_mass()

◆ GetForceInWorld()

◆ has_quaternion_dofs()

◆ index()

◆ is_floating()

◆ is_locked()

◆ Lock()

◆ mobod_index()

◆ name()

◆ node_index()

◆ operator=() [1/2]

◆ operator=() [2/2]

◆ scoped_name()

◆ Unlock()

Friends And Related Function Documentation

◆ internal::BodyAttorney< T >

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