Detailed Description

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

Frame is an abstract class representing a material frame (also called a physical frame) of its underlying RigidBody (Link).

The Frame's origin is a material point of its RigidBody, and its axes have fixed directions in that body. A Frame's pose (position and orientation) with respect to its RigidBodyFrame (LinkFrame) may be parameterized, but is fixed (not time or state dependent) once parameters have been set.

An important characteristic of a Frame is that forces or torques applied to a Frame are applied to the Frame's underlying body. Force-producing elements like joints, actuators, and constraints usually employ two Frames, with one Frame connected to one body and the other connected to a different body. Every Frame F can report the Link (RigidBody) L to which it is attached and its pose X_LF with respect to L's LinkFrame (RigidBodyFrame).

A Frame's pose in World (or relative to other frames) is always calculated starting with its pose relative to its underlying LinkFrame. Subclasses derived from Frame differ in how kinematic calculations are performed. For example, the angular velocity of a FixedOffsetFrame or LinkFrame (RigidBodyFrame) is identical to the angular velocity of its underlying body, whereas the translational velocity of a FixedOffsetFrame differs from that of a LinkFrame.

Frame provides methods for obtaining its current orientation, position, motion, etc. from a Context passed to those methods.

Note: For historical reasons, many of the method names here use "Body" to mean "Link". The distinction matters when we form composite bodies, which consist of multiple links welded together. Those composites form a single rigid body in the physics sense. Frames only know about their Links, not how they may have been combined into a composite body.

Template Parameters

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

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

Public Member Functions
	~Frame () override
FrameIndex	index () const
	Returns this element's unique index.
const RigidBody< T > &	body () const
	Returns a const reference to the RigidBody (Link) to which this Frame is attached (synonym for link()).
const Link< T > &	link () const
	Returns a const reference to the Link (RigidBody) to which this Frame is attached (synonym for body()).
bool	is_world_frame () const
	Returns true if this is the world frame.
bool	is_body_frame () const
	Returns true if this is the RigidBodyFrame (LinkFrame) of the associated RigidBody (Link).
bool	is_link_frame () const
	Returns true if this is the LinkFrame (RigidBodyFrame) of the associated Link (RigidBody).
const std::string &	name () const
	Returns the name of this frame. The name will never be empty.
ScopedName	scoped_name () const
	Returns scoped name of this frame.
const math::RigidTransform< T > &	EvalPoseInBodyFrame (const systems::Context< T > &context) const
	Returns a reference to the link-relative pose X_LF giving the pose of this Frame with respect to its link's LinkFrame (RigidBodyFrame).
math::RigidTransform< T >	CalcPoseInBodyFrame (const systems::Context< T > &context) const
	Returns the pose X_LF of this frame F in the LinkFrame (RigidBodyFrame) L of this Frame's Link (RigidBody).
math::RotationMatrix< T >	CalcRotationMatrixInBodyFrame (const systems::Context< T > &context) const
	Returns the rotation matrix R_LF that relates link frame L to this frame F (L is the LinkFrame of the Link (RigidBody) to which this frame F is attached).
virtual math::RigidTransform< T >	GetFixedPoseInBodyFrame () const
	Variant of CalcPoseInBodyFrame() that returns the fixed pose X_LF of this frame F in the link frame L associated with this frame.
virtual math::RotationMatrix< T >	GetFixedRotationMatrixInBodyFrame () const
	Returns the rotation matrix R_LF that relates link frame L to this frame F (L is the LinkFrame of the Link (RigidBody) to which this frame F is attached).
math::RigidTransform< T >	CalcOffsetPoseInBody (const systems::Context< T > &context, const math::RigidTransform< T > &X_FQ) const
	Given the offset pose X_FQ of a frame Q in this frame F, this method computes the pose X_LQ of frame Q in the link frame L of the Link (RigidBody) to which this frame is attached.
math::RotationMatrix< T >	CalcOffsetRotationMatrixInBody (const systems::Context< T > &context, const math::RotationMatrix< T > &R_FQ) const
	Calculates and returns the rotation matrix R_LQ that relates link frame L to frame Q via this intermediate frame F, i.e., R_LQ = R_LF * R_FQ (L is the link frame of the Link (RigidBody) to which this frame F is attached).
virtual math::RigidTransform< T >	GetFixedOffsetPoseInBody (const math::RigidTransform< T > &X_FQ) const
	Variant of CalcOffsetPoseInBody() that given the offset pose X_FQ of a frame Q in this frame F, returns the pose X_LQ of frame Q in the link frame L to which this frame is attached.
virtual math::RotationMatrix< T >	GetFixedRotationMatrixInBody (const math::RotationMatrix< T > &R_FQ) const
	Calculates and returns the rotation matrix R_LQ that relates link frame L to frame Q via this intermediate frame F, i.e., R_LQ = R_LF * R_FQ (L is the link frame of the Link (RigidBody) to which this frame F is attached).
math::RigidTransform< T >	CalcPoseInWorld (const systems::Context< T > &context) const
	Computes and returns the pose X_WF of this frame F in the world frame W as a function of the state of the model stored in context.
math::RigidTransform< T >	CalcPose (const systems::Context< T > &context, const Frame< T > &frame_M) const
	Computes and returns the pose X_MF of this frame F in measured in frame_M as a function of the state of the model stored in context.
math::RotationMatrix< T >	CalcRotationMatrix (const systems::Context< T > &context, const Frame< T > &frame_M) const
	Calculates and returns the rotation matrix R_MF that relates frame_M and this frame F as a function of the state stored in context.
math::RotationMatrix< T >	CalcRotationMatrixInWorld (const systems::Context< T > &context) const
	Calculates and returns the rotation matrix R_WF that relates the world frame W and this frame F as a function of the state stored in context.
const Vector3< T > &	EvalAngularVelocityInWorld (const systems::Context< T > &context) const
	Evaluates this frame F's angular velocity measured and expressed in the world frame W.
Vector3< T >	CalcAngularVelocity (const systems::Context< T > &context, const Frame< T > &measured_in_frame, const Frame< T > &expressed_in_frame) const
	Calculates this frame F's angular velocity measured in a frame M, expressed in a frame E.
SpatialVelocity< T >	CalcSpatialVelocityInWorld (const systems::Context< T > &context) const
	Calculates this frame F's spatial velocity measured and expressed in the world frame W.
SpatialVelocity< T >	CalcSpatialVelocity (const systems::Context< T > &context, const Frame< T > &frame_M, const Frame< T > &frame_E) const
	Calculates this frame F's spatial velocity measured in a frame M, expressed in a frame E.
SpatialVelocity< T >	CalcRelativeSpatialVelocityInWorld (const systems::Context< T > &context, const Frame< T > &other_frame) const
	Calculates this frame F's spatial velocity relative to another frame B, measured and expressed in the world frame W.
SpatialVelocity< T >	CalcRelativeSpatialVelocity (const systems::Context< T > &context, const Frame< T > &other_frame, const Frame< T > &measured_in_frame, const Frame< T > &expressed_in_frame) const
	Calculates this frame F's spatial velocity relative to another frame B, measured in a frame M, expressed in a frame E.
SpatialAcceleration< T >	CalcSpatialAccelerationInWorld (const systems::Context< T > &context) const
	Calculates this frame F's spatial acceleration measured and expressed in the world frame W.
SpatialAcceleration< T >	CalcSpatialAcceleration (const systems::Context< T > &context, const Frame< T > &measured_in_frame, const Frame< T > &expressed_in_frame) const
	Calculates this frame F's spatial acceleration measured in a frame M, expressed in a frame E.
SpatialAcceleration< T >	CalcRelativeSpatialAccelerationInWorld (const systems::Context< T > &context, const Frame< T > &other_frame) const
	Calculates this frame F's spatial acceleration relative to another frame B, measured and expressed in the world frame W.
SpatialAcceleration< T >	CalcRelativeSpatialAcceleration (const systems::Context< T > &context, const Frame< T > &other_frame, const Frame< T > &measured_in_frame, const Frame< T > &expressed_in_frame) const
	Calculates this frame F's spatial acceleration relative to another frame B, measured in a frame M, expressed in a frame E.
template<typename ToScalar>
std::unique_ptr< Frame< ToScalar > >	CloneToScalar (const internal::MultibodyTree< ToScalar > &tree_clone) const
	(Advanced) NVI to DoCloneToScalar() templated on the scalar type of the new clone to be created.
std::unique_ptr< Frame< T > >	ShallowClone () const
	(Internal use only) Returns a shallow clone (i.e., dependent elements such as bodies are aliased, not copied) that is not associated with any MbT (so the assigned index, if any, is discarded).
Does not allow copy, move, or assignment
	Frame (const Frame &)=delete
Frame &	operator= (const Frame &)=delete
	Frame (Frame &&)=delete
Frame &	operator= (Frame &&)=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.
template<typename = void>
const MultibodyPlant< T > &	GetParentPlant () const
	Returns the MultibodyPlant that owns this MultibodyElement.
void	DeclareParameters (internal::MultibodyTreeSystem< T > *tree_system)
	Declares MultibodyTreeSystem Parameters at MultibodyTreeSystem::Finalize() time.
void	SetDefaultParameters (systems::Parameters< T > *parameters) const
	Sets default values of parameters belonging to each MultibodyElement in parameters at a call to MultibodyTreeSystem::SetDefaultParameters().
void	DeclareDiscreteState (internal::MultibodyTreeSystem< T > *tree_system)
	Declares MultibodyTreeSystem discrete states.
void	DeclareCacheEntries (internal::MultibodyTreeSystem< T > *tree_system)
	(Advanced) Declares all cache entries needed by this element.
bool	is_ephemeral () const
	Returns true if this MultibodyElement was added during Finalize() rather than something a user added.
void	set_is_ephemeral (bool is_ephemeral)
	(Internal use only) Sets the is_ephemeral flag to the indicated value.
	MultibodyElement (const MultibodyElement &)=delete
MultibodyElement &	operator= (const MultibodyElement &)=delete
	MultibodyElement (MultibodyElement &&)=delete
MultibodyElement &	operator= (MultibodyElement &&)=delete

Protected Member Functions
virtual math::RigidTransform< T >	DoCalcPoseInBodyFrame (const systems::Parameters< T > &parameters) const =0
virtual math::RotationMatrix< T >	DoCalcRotationMatrixInBodyFrame (const systems::Parameters< T > &parameters) const =0
virtual math::RigidTransform< T >	DoCalcOffsetPoseInBody (const systems::Parameters< T > &parameters, const math::RigidTransform< T > &X_FQ) const
virtual math::RotationMatrix< T >	DoCalcOffsetRotationMatrixInBody (const systems::Parameters< T > &parameters, const math::RotationMatrix< T > &R_FQ) const
Methods to make a clone, optionally templated on different scalar
types. The first three 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 Frame subclasses might specify a number of prerequisites on the cloned tree and therefore require it to be at a given state of cloning. See MultibodyTree::CloneToScalar() for a list of prerequisites that are guaranteed to be satisfied during the cloning process.
virtual std::unique_ptr< Frame< double > >	DoCloneToScalar (const internal::MultibodyTree< double > &tree_clone) const =0
	Clones this Frame (templated on T) to a frame templated on double.
virtual std::unique_ptr< Frame< AutoDiffXd > >	DoCloneToScalar (const internal::MultibodyTree< AutoDiffXd > &tree_clone) const =0
	Clones this Frame (templated on T) to a frame templated on AutoDiffXd.
virtual std::unique_ptr< Frame< symbolic::Expression > >	DoCloneToScalar (const internal::MultibodyTree< symbolic::Expression > &) const =0
virtual std::unique_ptr< Frame< T > >	DoShallowClone () const
	NVI for ShallowClone().
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.
	MultibodyElement (ModelInstanceIndex model_instance)
	Constructor which allows specifying a model instance.
	MultibodyElement (ModelInstanceIndex model_instance, int64_t index)
	Both the model instance and element index are specified.
template<typename ElementIndexType>
ElementIndexType	index_impl () const
	Returns this element's unique index.
template<typename ElementOrdinalType = int64_t>
ElementOrdinalType	ordinal_impl () const
	Returns this element's unique ordinal.
const internal::MultibodyTree< T > &	get_parent_tree () const
	Returns a constant reference to the parent MultibodyTree that owns this element.
const internal::MultibodyTreeSystem< T > &	GetParentTreeSystem () const
	Returns a constant reference to the parent MultibodyTreeSystem that owns the parent MultibodyTree that owns this element.
void	SetTopology ()
	(Internal use only) Gives MultibodyElement-derived objects the opportunity to set data members that depend on topology and coordinate assignments having been finalized.
virtual void	DoDeclareDiscreteState (internal::MultibodyTreeSystem< T > *)
	Implementation of the NVI DeclareDiscreteState().
virtual void	DoDeclareCacheEntries (internal::MultibodyTreeSystem< T > *)
	Derived classes must override this method to declare cache entries needed by this element.
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().
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().
systems::DiscreteStateIndex	DeclareDiscreteState (internal::MultibodyTreeSystem< T > *tree_system, const VectorX< T > &model_value)
	To be used by MultibodyElement-derived objects when declaring discrete states in their implementation of DoDeclareDiscreteStates().
systems::CacheEntry &	DeclareCacheEntry (internal::MultibodyTreeSystem< T > *tree_system, std::string description, systems::ValueProducer value_producer, std::set< systems::DependencyTicket > prerequisites_of_calc)
	To be used by MultibodyElement-derived objects when declaring cache entries in their implementation of DoDeclareCacheEntries().
bool	has_parent_tree () const
	Returns true if this multibody element has a parent tree, otherwise false.

Internal use only
These functions work directly with the frame body pose cache entry.
const math::RigidTransform< T > &	get_X_LF (const internal::FrameBodyPoseCache< T > &frame_body_poses) const
	(Internal use only) A Frame's pose-in-parent-frame X_PF can be parameterized, the parent frame's pose may also be parameterized, and so on.
const math::RigidTransform< T > &	get_X_BF (const internal::FrameBodyPoseCache< T > &frame_body_poses) const
	(Internal use only) Given an already up-to-date frame body pose cache, extract X_BF for this Frame from it.
const math::RigidTransform< T > &	get_X_FB (const internal::FrameBodyPoseCache< T > &frame_body_poses) const
	(Internal use only) Given an already up-to-date frame body pose cache, extract X_FB (=X_BF⁻¹) for this Frame from it.
bool	is_X_BF_identity (const internal::FrameBodyPoseCache< T > &frame_body_poses) const
	(Internal use only) Given an already up-to-date frame body pose cache, returns whether X_BF (and thus X_FB) is exactly identity.
	Frame (const std::string &name, const Link< T > &link, std::optional< ModelInstanceIndex > model_instance={})
	Only derived classes can use this constructor.
virtual void	DoDeclareFrameParameters (internal::MultibodyTreeSystem< T > *)
	Called by DoDeclareParameters().
virtual void	DoSetDefaultFrameParameters (systems::Parameters< T > *) const
	Called by DoSetDefaultParameters().

Constructor & Destructor Documentation

◆ Frame() [1/3]

template<typename T>

Frame ( const Frame< T > & )

delete

◆ Frame() [2/3]

template<typename T>

Frame ( Frame< T > && )

delete

◆ ~Frame()

template<typename T>

~Frame ( )

override

◆ Frame() [3/3]

template<typename T>

Frame	(	const std::string &	name,
		const Link< T > &	link,
		std::optional< ModelInstanceIndex >	model_instance = {} )

explicitprotected

Only derived classes can use this constructor.

It creates a Frame object attached to link and puts the frame in the link's model instance.

Member Function Documentation

◆ body()

template<typename T>

const RigidBody< T > & body ( ) const

Returns a const reference to the RigidBody (Link) to which this Frame is attached (synonym for link()).

◆ CalcAngularVelocity()

template<typename T>

Vector3< T > CalcAngularVelocity	(	const systems::Context< T > &	context,
		const Frame< T > &	measured_in_frame,
		const Frame< T > &	expressed_in_frame ) const

Calculates this frame F's angular velocity measured in a frame M, expressed in a frame E.

Parameters

[in]	context	contains the state of the multibody system.
[in]	measured_in_frame	which is frame M (the frame in which this angular velocity is to be measured).
[in]	expressed_in_frame	which is frame E (the frame in which the returned angular velocity is to be expressed).

Returns: ω_MF_E, this frame F's angular velocity ω measured in frame M, expressed in frame E.

See also: EvalAngularVelocityInWorld() to evaluate ω_WF_W (this frame F's angular velocity ω measured and expressed in the world frame W).

◆ CalcOffsetPoseInBody()

template<typename T>

math::RigidTransform< T > CalcOffsetPoseInBody	(	const systems::Context< T > &	context,
		const math::RigidTransform< T > &	X_FQ ) const

Given the offset pose X_FQ of a frame Q in this frame F, this method computes the pose X_LQ of frame Q in the link frame L of the Link (RigidBody) to which this frame is attached.

In other words, if the pose of this frame F in the link frame L is X_LF, this method computes the pose X_LQ of frame Q in the link frame L as X_LQ = X_LF * X_FQ. In particular, if this is the link frame L, i.e. X_LF is identically the identity transform, this method directly returns X_FQ. Specific frame subclasses can override this method to provide faster implementations if needed.

◆ CalcOffsetRotationMatrixInBody()

template<typename T>

math::RotationMatrix< T > CalcOffsetRotationMatrixInBody	(	const systems::Context< T > &	context,
		const math::RotationMatrix< T > &	R_FQ ) const

Calculates and returns the rotation matrix R_LQ that relates link frame L to frame Q via this intermediate frame F, i.e., R_LQ = R_LF * R_FQ (L is the link frame of the Link (RigidBody) to which this frame F is attached).

Parameters

[in] R_FQ rotation matrix that relates frame F to frame Q.

◆ CalcPose()

template<typename T>

math::RigidTransform< T > CalcPose	(	const systems::Context< T > &	context,
		const Frame< T > &	frame_M ) const

Computes and returns the pose X_MF of this frame F in measured in frame_M as a function of the state of the model stored in context.

See also: CalcPoseInWorld().

◆ CalcPoseInBodyFrame()

template<typename T>

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

Returns the pose X_LF of this frame F in the LinkFrame (RigidBodyFrame) L of this Frame's Link (RigidBody).

In particular, if this is the link frame L, this method directly returns the identity transformation. Note that this ONLY depends on the Parameters in the context; it does not depend on time, input, state, etc.

◆ CalcPoseInWorld()

template<typename T>

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

Computes and returns the pose X_WF of this frame F in the world frame W as a function of the state of the model stored in context.

Note: RigidBody::EvalPoseInWorld() provides a more efficient way to obtain the pose for a RigidBodyFrame (LinkFrame).

◆ CalcRelativeSpatialAcceleration()

template<typename T>

SpatialAcceleration< T > CalcRelativeSpatialAcceleration	(	const systems::Context< T > &	context,
		const Frame< T > &	other_frame,
		const Frame< T > &	measured_in_frame,
		const Frame< T > &	expressed_in_frame ) const

Calculates this frame F's spatial acceleration relative to another frame B, measured in a frame M, expressed in a frame E.

Parameters

[in]	context	contains the state of the multibody system.
[in]	other_frame	which is frame B.
[in]	measured_in_frame	which is frame M.
[in]	expressed_in_frame	which is frame E.

Returns: A_M_BF_E = A_MF_E - A_MB_E, frame F's spatial acceleration relative to frame B, measured in frame M, expressed in frame E.

In general, A_M_BF = DtW(V_M_BF), the time-derivative in frame M of frame F's spatial velocity relative to frame B. The rotational part of the returned quantity is α_MF_E - α_MB_E = DtM(ω_BF)_E. Note: For 3D analysis, DtM(ω_BF) ≠ α_BF. The translational part of the returned quantity is a_M_BoFo_E (Fo's translational acceleration relative to Bo, measured in frame M, expressed in frame E).

 α_MF_E - α_MB_E = DtM(ω_MF)_E - DtM(ω_MB)_E = DtM(ω_BF)_E
 a_M_BoFo_E = a_MFo_E - a_MBo_E = DtM(v_MFo) - DtM(v_MBo) = Dt²M(p_BoFo)_E

where Dt²M(p_BoFo)_E is the 2ⁿᵈ time-derivative in frame M of p_BoFo (the position vector from Bo to Fo), and this result is expressed in frame E.

Note: The calculation of the 2ⁿᵈ time-derivative of the distance between Bo and Fo can be done with relative translational acceleration, but this calculation does not depend on the measured-in-frame, hence in this case, consider CalcRelativeSpatialAccelerationInWorld() since it is faster.

See also: CalcSpatialAccelerationInWorld(), CalcSpatialAcceleration(), and CalcRelativeSpatialAccelerationInWorld().

◆ CalcRelativeSpatialAccelerationInWorld()

template<typename T>

SpatialAcceleration< T > CalcRelativeSpatialAccelerationInWorld	(	const systems::Context< T > &	context,
		const Frame< T > &	other_frame ) const

Calculates this frame F's spatial acceleration relative to another frame B, measured and expressed in the world frame W.

Parameters

[in]	context	contains the state of the multibody system.
[in]	other_frame	which is frame B.

Returns: A_W_BF_W = A_WF_W - A_WB_W, frame F's spatial acceleration relative to frame B, measured and expressed in the world frame W.

In general, A_W_BF = DtW(V_W_BF), the time-derivative in the world frame W of frame F's spatial velocity relative to frame B. The rotational part of the returned quantity is α_WF_W - α_WB_W = DtW(ω_BF)_W. For 3D analysis, DtW(ω_BF) ≠ α_BF. The translational part of the returned quantity is a_W_BoFo_W (Fo's translational acceleration relative to Bo, measured and expressed in world frame W).

 α_WF_W - α_WB_W = DtW(ω_WF)_W - DtW(ω_WB)_W = DtW(ω_BF)_W
 a_W_BoFo_W = a_WFo_W - a_WBo_W = DtW(v_WFo) - DtW(v_WBo) = Dt²W(p_BoFo)_W

where Dt²W(p_BoFo)_W is the 2ⁿᵈ time-derivative in frame W of p_BoFo (the position vector from Bo to Fo), and this result is expressed in frame W.

Note: The method CalcSpatialAccelerationInWorld() is more efficient and coherent if any of this, other_frame, or the world frame W are the same.

See also: CalcSpatialAccelerationInWorld(), CalcRelativeSpatialAcceleration().

◆ CalcRelativeSpatialVelocity()

template<typename T>

SpatialVelocity< T > CalcRelativeSpatialVelocity	(	const systems::Context< T > &	context,
		const Frame< T > &	other_frame,
		const Frame< T > &	measured_in_frame,
		const Frame< T > &	expressed_in_frame ) const

Calculates this frame F's spatial velocity relative to another frame B, measured in a frame M, expressed in a frame E.

Parameters

[in]	context	contains the state of the multibody system.
[in]	other_frame	which is frame B.
[in]	measured_in_frame	which is frame M.
[in]	expressed_in_frame	which is frame E.

Returns

V_M_BF_E = V_MF_E - V_MB_E, frame F's spatial velocity relative to frame B, measured in frame M, expressed in frame E. The rotational part of the returned quantity is ω_BF_E (F's angular velocity measured in B and expressed in E). The translational part is v_M_BoFo_E (Fo's translational velocity relative to Bo, measured in M, and expressed in E).

 ω_BF_E = ω_MF_E - ω_MB_E
 v_M_BoFo_E = v_MFo_E - v_MBo_E = DtM(p_BoFo)

where DtM(p_BoFo) is the time-derivative in frame M of p_BoFo (position vector from Bo to Fo), and this vector is expressed in frame E.

Note: The method CalcSpatialVelocity() is more efficient and coherent if any of this, other_frame, or measured_in_frame are the same. Also, the value of V_M_BoFo does not depend on the measured_in_frame if Bo and Fo are coincident (i.e., p_BoFo = 0), in which case consider the more efficient method CalcRelativeSpatialVelocityInWorld(). Lastly, the calculation of elongation between Bo and Fo can be done with relative translational velocity, but elongation does not depend on the measured-in-frame (hence consider CalcRelativeSpatialVelocityInWorld()).

See also: CalcSpatialVelocityInWorld(), CalcSpatialVelocity(), and CalcRelativeSpatialVelocityInWorld().

◆ CalcRelativeSpatialVelocityInWorld()

template<typename T>

SpatialVelocity< T > CalcRelativeSpatialVelocityInWorld	(	const systems::Context< T > &	context,
		const Frame< T > &	other_frame ) const

Calculates this frame F's spatial velocity relative to another frame B, measured and expressed in the world frame W.

Parameters

[in]	context	contains the state of the multibody system.
[in]	other_frame	which is frame B.

Returns

V_W_BF_W = V_WF_W - V_WB_W, frame F's spatial velocity relative to frame B, measured and expressed in the world frame W. The rotational part of the returned quantity is ω_BF_W (F's angular velocity measured in B and expressed in W). The translational part is v_W_BoFo_W (Fo's translational velocity relative to Bo, measured and expressed in world frame W).

    ω_BF_W  = ω_WF_W - ω_WB_W
 v_W_BoFo_W = v_WFo_W - v_WBo_W = DtW(p_BoFo)

where DtW(p_BoFo) is the time-derivative in frame W of p_BoFo (position vector from Bo to Fo), and this vector is expressed in frame W.

Note: The method CalcSpatialVelocityInWorld() is more efficient and coherent if any of this, other_frame, or the world frame W are the same.

See also: CalcSpatialVelocityInWorld() and CalcRelativeSpatialVelocity().

◆ CalcRotationMatrix()

template<typename T>

math::RotationMatrix< T > CalcRotationMatrix	(	const systems::Context< T > &	context,
		const Frame< T > &	frame_M ) const

Calculates and returns the rotation matrix R_MF that relates frame_M and this frame F as a function of the state stored in context.

◆ CalcRotationMatrixInBodyFrame()

template<typename T>

math::RotationMatrix< T > CalcRotationMatrixInBodyFrame ( const systems::Context< T > & context ) const

Returns the rotation matrix R_LF that relates link frame L to this frame F (L is the LinkFrame of the Link (RigidBody) to which this frame F is attached).

Note: If this is L, this method returns the identity RotationMatrix. Note that this ONLY depends on the Parameters in the context; it does not depend on time, input, state, etc.

◆ CalcRotationMatrixInWorld()

template<typename T>

math::RotationMatrix< T > CalcRotationMatrixInWorld ( const systems::Context< T > & context ) const

Calculates and returns the rotation matrix R_WF that relates the world frame W and this frame F as a function of the state stored in context.

◆ CalcSpatialAcceleration()

template<typename T>

SpatialAcceleration< T > CalcSpatialAcceleration	(	const systems::Context< T > &	context,
		const Frame< T > &	measured_in_frame,
		const Frame< T > &	expressed_in_frame ) const

Calculates this frame F's spatial acceleration measured in a frame M, expressed in a frame E.

Parameters

[in]	context	contains the state of the multibody system.
[in]	measured_in_frame	which is frame M.
[in]	expressed_in_frame	which is frame E.

Returns

A_MF_E, this frame F's spatial acceleration measured in frame M, expressed in frame E. The rotational part of the returned quantity is α_MF_E (frame F's angular acceleration α measured in frame M, expressed in frame E). The translational part is a_MFo_E (translational acceleration of frame F's origin point Fo, measured in frame M, expressed in frame E). Although α_MF is defined below in terms of DtM(ω_MF), the time-derivative in frame M of ω_MF, the actual calculation of α_MF avoids differentiation. Similarly for the definition vs. calculation for a_MFo.

 α_MF = DtM(ω_MF)           ω_MF is frame F's angular velocity in frame M.
 a_MFo = DtM(v_MFo)    v_MF is Fo's translational acceleration in frame M.

See also: CalcSpatialAccelerationInWorld() and CalcSpatialVelocity().

◆ CalcSpatialAccelerationInWorld()

template<typename T>

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

Calculates this frame F's spatial acceleration measured and expressed in the world frame W.

Parameters

[in] context contains the state of the multibody system.

Returns: A_WF_W, this frame F's spatial acceleration measured and expressed in the world frame W. The rotational part of the returned quantity is α_WF_E (frame F's angular acceleration α measured and expressed in the world frame W). The translational part is a_WFo_W (translational acceleration of frame F's origin point Fo, measured and expressed in the world frame W).

Note: RigidBody::EvalSpatialAccelerationInWorld() provides a more efficient way to obtain a body frame's spatial acceleration measured in the world frame.; 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.

See also: CalcSpatialAcceleration() and CalcSpatialVelocityInWorld().

◆ CalcSpatialVelocity()

template<typename T>

SpatialVelocity< T > CalcSpatialVelocity	(	const systems::Context< T > &	context,
		const Frame< T > &	frame_M,
		const Frame< T > &	frame_E ) const

Calculates this frame F's spatial velocity measured in a frame M, expressed in a frame E.

Parameters

[in]	context	contains the state of the multibody system.
[in]	frame_M	which is the measured_in_frame.
[in]	frame_E	which is the expressed_in_frame.

Returns: V_MF_E, this frame F's spatial velocity measured in frame M, expressed in frame E. The rotational part of the returned quantity is ω_MF_E (frame F's angular velocity ω measured in frame M, expressed in frame E). The translational part is v_MFo_E (translational velocity v of frame F's origin point Fo, measured in frame M, expressed in frame E).

See also: CalcSpatialVelocityInWorld(), CalcRelativeSpatialVelocity(), and CalcSpatialAcceleration().

◆ CalcSpatialVelocityInWorld()

template<typename T>

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

Calculates this frame F's spatial velocity measured and expressed in the world frame W.

Parameters

[in] context contains the state of the multibody system.

Returns: V_WF_W, this frame F's spatial velocity measured and expressed in the world frame W. The rotational part of the returned quantity is ω_WF_W (frame F's angular velocity ω measured and expressed in the world frame W). The translational part is v_WFo_W (translational velocity v of frame F's origin point Fo, measured and expressed in the world frame W).

Note: RigidBody::EvalSpatialVelocityInWorld() provides a more efficient way to obtain a RigidBodyFrame (LinkFrame) spatial velocity measured in the world frame.

See also: CalcSpatialVelocity(), CalcRelativeSpatialVelocityInWorld(), and CalcSpatialAccelerationInWorld().

◆ CloneToScalar()

template<typename T>

template<typename ToScalar>

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

(Advanced) NVI 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()

◆ DoCalcOffsetPoseInBody()

template<typename T>

virtual math::RigidTransform< T > DoCalcOffsetPoseInBody	(	const systems::Parameters< T > &	parameters,
		const math::RigidTransform< T > &	X_FQ ) const

protectedvirtual

Reimplemented in RigidBodyFrame< T >, and RigidBodyFrame< double >.

◆ DoCalcOffsetRotationMatrixInBody()

template<typename T>

virtual math::RotationMatrix< T > DoCalcOffsetRotationMatrixInBody	(	const systems::Parameters< T > &	parameters,
		const math::RotationMatrix< T > &	R_FQ ) const

protectedvirtual

Reimplemented in RigidBodyFrame< T >, and RigidBodyFrame< double >.

◆ DoCalcPoseInBodyFrame()

template<typename T>

virtual math::RigidTransform< T > DoCalcPoseInBodyFrame ( const systems::Parameters< T > & parameters ) const

protectedpure virtual

Implemented in FixedOffsetFrame< T >, RigidBodyFrame< T >, and RigidBodyFrame< double >.

◆ DoCalcRotationMatrixInBodyFrame()

template<typename T>

virtual math::RotationMatrix< T > DoCalcRotationMatrixInBodyFrame ( const systems::Parameters< T > & parameters ) const

protectedpure virtual

Implemented in FixedOffsetFrame< T >, RigidBodyFrame< T >, and RigidBodyFrame< double >.

◆ DoCloneToScalar() [1/3]

template<typename T>

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

protectedpure virtual

Clones this Frame (templated on T) to a frame templated on AutoDiffXd.

Implemented in FixedOffsetFrame< T >, and RigidBodyFrame< T >.

◆ DoCloneToScalar() [2/3]

template<typename T>

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

protectedpure virtual

Clones this Frame (templated on T) to a frame templated on double.

Implemented in FixedOffsetFrame< T >, RigidBodyFrame< T >, and RigidBodyFrame< double >.

◆ DoCloneToScalar() [3/3]

template<typename T>

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

protectedpure virtual

Implemented in FixedOffsetFrame< T >, and RigidBodyFrame< T >.

◆ DoDeclareFrameParameters()

template<typename T>

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

protectedvirtual

Called by DoDeclareParameters().

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

◆ DoSetDefaultFrameParameters()

template<typename T>

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

protectedvirtual

Called by DoSetDefaultParameters().

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

◆ DoShallowClone()

template<typename T>

virtual std::unique_ptr< Frame< T > > DoShallowClone ( ) const

protectedvirtual

NVI for ShallowClone().

Reimplemented in FixedOffsetFrame< T >, RigidBodyFrame< T >, and RigidBodyFrame< double >.

◆ EvalAngularVelocityInWorld()

template<typename T>

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

Evaluates this frame F's angular velocity measured and expressed in the world frame W.

Parameters

[in] context contains the state of the multibody system.

Returns: ω_WF_W (frame F's angular velocity ω measured and expressed in the world frame W).

See also: CalcAngularVelocity() to calculate ω_MF_E (this frame F's angular velocity ω measured in a frame M and expressed in a frame E).

◆ EvalPoseInBodyFrame()

template<typename T>

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

Returns a reference to the link-relative pose X_LF giving the pose of this Frame with respect to its link's LinkFrame (RigidBodyFrame).

This may depend on parameters in the Context but not on time or state. The first time this is called after a parameter change will precalculate offset poses for all Frames into the Context's cache; subsequent calls on any Frame are very fast.

◆ get_X_BF()

template<typename T>

const math::RigidTransform< T > & get_X_BF ( const internal::FrameBodyPoseCache< T > & frame_body_poses ) const

(Internal use only) Given an already up-to-date frame body pose cache, extract X_BF for this Frame from it.

Note that X_BF is F's pose on its mobilized body B which might not be the same as its link L.

Note: Be sure you have called MultibodyTreeSystem::EvalFrameBodyPoses() since the last parameter change; we can't check here.

Return values

X_BF	pose of this frame in its Mobod's frame

◆ get_X_FB()

template<typename T>

const math::RigidTransform< T > & get_X_FB ( const internal::FrameBodyPoseCache< T > & frame_body_poses ) const

(Internal use only) Given an already up-to-date frame body pose cache, extract X_FB (=X_BF⁻¹) for this Frame from it.

Note: Be sure you have called MultibodyTreeSystem::EvalFrameBodyPoses() since the last parameter change; we can't check here.

Return values

X_FB	inverse of this frame's pose in its Mobod's frame

◆ get_X_LF()

template<typename T>

const math::RigidTransform< T > & get_X_LF ( const internal::FrameBodyPoseCache< T > & frame_body_poses ) const

(Internal use only) A Frame's pose-in-parent-frame X_PF can be parameterized, the parent frame's pose may also be parameterized, and so on.

Thus the calculation of this frame's pose in its link frame (X_LF) can be expensive. There is a cache entry that holds the calculated X_LF, evaluated whenever parameters change. This allows us to grab X_LF as a const reference rather than having to extract and reformat parameters, and compose with parent and ancestor poses at runtime.

When we are optimizing assemblies using composite Mobods, the pose of a frame on its Mobod (X_BF) can differ from its pose on its Link (X_LF). Most multibody computations need X_BF, but X_LF is available also. (Internal use only) Given an already up-to-date frame body pose cache, extract X_LF for this Frame from it.

Note: Be sure you have called MultibodyTreeSystem::EvalFrameBodyPoses() since the last parameter change; we can't check here.

Return values

X_LF	pose of this frame in its Link's frame

◆ GetFixedOffsetPoseInBody()

template<typename T>

virtual math::RigidTransform< T > GetFixedOffsetPoseInBody ( const math::RigidTransform< T > & X_FQ ) const

virtual

Variant of CalcOffsetPoseInBody() that given the offset pose X_FQ of a frame Q in this frame F, returns the pose X_LQ of frame Q in the link frame L to which this frame is attached.

Exceptions

std::exception if called on a Frame that does not have a fixed offset in the body frame.

Reimplemented in RigidBodyFrame< T >, and RigidBodyFrame< double >.

◆ GetFixedPoseInBodyFrame()

template<typename T>

virtual math::RigidTransform< T > GetFixedPoseInBodyFrame ( ) const

virtual

Variant of CalcPoseInBodyFrame() that returns the fixed pose X_LF of this frame F in the link frame L associated with this frame.

Exceptions

std::exception if called on a Frame that does not have a fixed offset in the body frame.

Reimplemented in FixedOffsetFrame< T >, RigidBodyFrame< T >, and RigidBodyFrame< double >.

◆ GetFixedRotationMatrixInBody()

template<typename T>

virtual math::RotationMatrix< T > GetFixedRotationMatrixInBody ( const math::RotationMatrix< T > & R_FQ ) const

virtual

Calculates and returns the rotation matrix R_LQ that relates link frame L to frame Q via this intermediate frame F, i.e., R_LQ = R_LF * R_FQ (L is the link frame of the Link (RigidBody) to which this frame F is attached).

Parameters

[in] R_FQ rotation matrix that relates frame F to frame Q.

Exceptions

std::exception if this frame F is a Frame that does not have a fixed offset in the link frame L (i.e., R_LF is not constant).

Reimplemented in RigidBodyFrame< T >, and RigidBodyFrame< double >.

◆ GetFixedRotationMatrixInBodyFrame()

template<typename T>

virtual math::RotationMatrix< T > GetFixedRotationMatrixInBodyFrame ( ) const

virtual

Returns the rotation matrix R_LF that relates link frame L to this frame F (L is the LinkFrame of the Link (RigidBody) to which this frame F is attached).

Exceptions

std::exception if this frame F is a Frame that does not have a fixed offset in the link frame L (i.e., R_LF is not constant). Frame sub-classes that have a constant R_LF must override this method.

Reimplemented in FixedOffsetFrame< T >, RigidBodyFrame< T >, and RigidBodyFrame< double >.

◆ index()

template<typename T>

FrameIndex index ( ) const

Returns this element's unique index.

◆ is_body_frame()

template<typename T>

bool is_body_frame ( ) const

Returns true if this is the RigidBodyFrame (LinkFrame) of the associated RigidBody (Link).

This is a synonym for is_link_frame().

◆ is_link_frame()

template<typename T>

bool is_link_frame ( ) const

Returns true if this is the LinkFrame (RigidBodyFrame) of the associated Link (RigidBody).

This is a synonym for is_body_frame().

◆ is_world_frame()

template<typename T>

bool is_world_frame ( ) const

Returns true if this is the world frame.

◆ is_X_BF_identity()

template<typename T>

bool is_X_BF_identity ( const internal::FrameBodyPoseCache< T > & frame_body_poses ) const

(Internal use only) Given an already up-to-date frame body pose cache, returns whether X_BF (and thus X_FB) is exactly identity.

This is precomputed in the cache so is very fast to check.

Note: Be sure you have called MultibodyTreeSystem::EvalFrameBodyPoses() since the last parameter change; we can't check here.

See also: get_X_BF(), get_X_FB()

◆ link()

template<typename T>

const Link< T > & link ( ) const

Returns a const reference to the Link (RigidBody) to which this Frame is attached (synonym for body()).

◆ name()

template<typename T>

const std::string & name ( ) const

Returns the name of this frame. The name will never be empty.

◆ operator=() [1/2]

template<typename T>

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

delete

◆ operator=() [2/2]

template<typename T>

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

delete

◆ scoped_name()

template<typename T>

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).

Exceptions

std::exception if this element is not associated with a MultibodyPlant.

◆ ShallowClone()

template<typename T>

std::unique_ptr< Frame< T > > ShallowClone ( ) const

(Internal use only) Returns a shallow clone (i.e., dependent elements such as bodies are aliased, not copied) that is not associated with any MbT (so the assigned index, if any, is discarded).

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

drake/multibody/tree/frame.h

Detailed Description

Public Member Functions

Protected Member Functions

Internal use only

Constructor & Destructor Documentation

◆ Frame() [1/3]

◆ Frame() [2/3]

◆ ~Frame()

◆ Frame() [3/3]

Member Function Documentation

◆ body()

◆ CalcAngularVelocity()

◆ CalcOffsetPoseInBody()

◆ CalcOffsetRotationMatrixInBody()

◆ CalcPose()

◆ CalcPoseInBodyFrame()

◆ CalcPoseInWorld()

◆ CalcRelativeSpatialAcceleration()

◆ CalcRelativeSpatialAccelerationInWorld()

◆ CalcRelativeSpatialVelocity()

◆ CalcRelativeSpatialVelocityInWorld()

◆ CalcRotationMatrix()

◆ CalcRotationMatrixInBodyFrame()

◆ CalcRotationMatrixInWorld()

◆ CalcSpatialAcceleration()

◆ CalcSpatialAccelerationInWorld()

◆ CalcSpatialVelocity()

◆ CalcSpatialVelocityInWorld()

◆ CloneToScalar()

◆ DoCalcOffsetPoseInBody()

◆ DoCalcOffsetRotationMatrixInBody()

◆ DoCalcPoseInBodyFrame()

◆ DoCalcRotationMatrixInBodyFrame()

◆ DoCloneToScalar() [1/3]

◆ DoCloneToScalar() [2/3]

◆ DoCloneToScalar() [3/3]

◆ DoDeclareFrameParameters()

◆ DoSetDefaultFrameParameters()

◆ DoShallowClone()

◆ EvalAngularVelocityInWorld()

◆ EvalPoseInBodyFrame()

◆ get_X_BF()

◆ get_X_FB()

◆ get_X_LF()

◆ GetFixedOffsetPoseInBody()

◆ GetFixedPoseInBodyFrame()

◆ GetFixedRotationMatrixInBody()

◆ GetFixedRotationMatrixInBodyFrame()

◆ index()

◆ is_body_frame()

◆ is_link_frame()

◆ is_world_frame()

◆ is_X_BF_identity()

◆ link()

◆ name()

◆ operator=() [1/2]

◆ operator=() [2/2]

◆ scoped_name()

◆ ShallowClone()