Drake
Drake C++ Documentation
RevoluteJoint< T > Class Template Referencefinal

Detailed Description

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

This Joint allows two bodies to rotate relatively to one another around a common axis.

That is, given a frame F attached to the parent body P and a frame M attached to the child body B (see the Joint class's documentation), this Joint allows frames F and M to rotate with respect to each other about an axis â. The rotation angle's sign is defined such that child body B rotates about axis â according to the right hand rule, with thumb aligned in the axis direction. Axis â is constant and has the same measures in both frames F and M, that is, â_F = â_M.

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

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

Public Types

template<typename Scalar >
using Context = systems::Context< Scalar >
 

Public Member Functions

 RevoluteJoint (const std::string &name, const Frame< T > &frame_on_parent, const Frame< T > &frame_on_child, const Vector3< double > &axis, double damping=0)
 Constructor to create a revolute joint between two bodies so that frame F attached to the parent body P and frame M attached to the child body B, rotate relatively to one another about a common axis. More...
 
 RevoluteJoint (const std::string &name, const Frame< T > &frame_on_parent, const Frame< T > &frame_on_child, const Vector3< double > &axis, double pos_lower_limit, double pos_upper_limit, double damping=0)
 Constructor to create a revolute joint between two bodies so that frame F attached to the parent body P and frame M attached to the child body B, rotate relatively to one another about a common axis. More...
 
const std::string & type_name () const override
 Returns a string identifying the type of this joint, such as "revolute" or "prismatic". More...
 
const Vector3< double > & revolute_axis () const
 Returns the axis of revolution of this joint as a unit vector. More...
 
double default_damping () const
 Returns this joint's default damping constant in N⋅m⋅s. More...
 
double damping () const
 (Deprecated.) More...
 
void set_default_damping (double damping)
 Sets the default value of viscous damping for this joint, in N⋅m⋅s. More...
 
double position_lower_limit () const
 Returns the position lower limit for this joint in radians. More...
 
double position_upper_limit () const
 Returns the position upper limit for this joint in radians. More...
 
double velocity_lower_limit () const
 Returns the velocity lower limit for this joint in radians / s. More...
 
double velocity_upper_limit () const
 Returns the velocity upper limit for this joint in radians / s. More...
 
double acceleration_lower_limit () const
 Returns the acceleration lower limit for this joint in radians / s². More...
 
double acceleration_upper_limit () const
 Returns the acceleration upper limit for this joint in radians / s². More...
 
double get_default_angle () const
 Gets the default rotation angle. More...
 
void set_default_angle (double angle)
 Sets the default_positions of this joint (in this case a single angle). More...
 
void AddInTorque (const systems::Context< T > &context, const T &torque, MultibodyForces< T > *forces) const
 Adds into forces a given torque for this joint that is to be applied about the joint's axis. More...
 
Does not allow copy, move, or assignment
 RevoluteJoint (const RevoluteJoint &)=delete
 
RevoluteJointoperator= (const RevoluteJoint &)=delete
 
 RevoluteJoint (RevoluteJoint &&)=delete
 
RevoluteJointoperator= (RevoluteJoint &&)=delete
 
Context-dependent value access
const T & get_angle (const Context< T > &context) const
 Gets the rotation angle of this mobilizer from context. More...
 
const RevoluteJoint< T > & set_angle (Context< T > *context, const T &angle) const
 Sets the context so that the generalized coordinate corresponding to the rotation angle of this joint equals angle. More...
 
void set_random_angle_distribution (const symbolic::Expression &angle)
 
const T & get_angular_rate (const Context< T > &context) const
 Gets the rate of change, in radians per second, of this joint's angle (see get_angle()) from context. More...
 
const RevoluteJoint< T > & set_angular_rate (Context< T > *context, const T &angle) const
 Sets the rate of change, in radians per second, of this this joint's angle to theta_dot. More...
 
const T & GetDamping (const Context< T > &context) const
 Returns the Context dependent damping coefficient stored as a parameter in context. More...
 
void SetDamping (Context< T > *context, const T &damping) const
 Sets the value of the viscous damping coefficient for this joint, stored as a parameter in context. More...
 
- Public Member Functions inherited from Joint< T >
 Joint (const std::string &name, const Frame< T > &frame_on_parent, const Frame< T > &frame_on_child, VectorX< double > damping, const VectorX< double > &pos_lower_limits, const VectorX< double > &pos_upper_limits, const VectorX< double > &vel_lower_limits, const VectorX< double > &vel_upper_limits, const VectorX< double > &acc_lower_limits, const VectorX< double > &acc_upper_limits)
 Creates a joint between two Frame objects which imposes a given kinematic relation between frame F attached on the parent body P and frame M attached on the child body B. More...
 
 Joint (const std::string &name, const Frame< T > &frame_on_parent, const Frame< T > &frame_on_child, const VectorX< double > &pos_lower_limits, const VectorX< double > &pos_upper_limits, const VectorX< double > &vel_lower_limits, const VectorX< double > &vel_upper_limits, const VectorX< double > &acc_lower_limits, const VectorX< double > &acc_upper_limits)
 Additional constructor overload for joints with zero damping. More...
 
virtual ~Joint ()
 
JointIndex index () const
 Returns this element's unique index. More...
 
const std::string & name () const
 Returns the name of this joint. More...
 
const RigidBody< T > & parent_body () const
 Returns a const reference to the parent body P. More...
 
const RigidBody< T > & child_body () const
 Returns a const reference to the child body B. More...
 
const Frame< T > & frame_on_parent () const
 Returns a const reference to the frame F attached on the parent body P. More...
 
const Frame< T > & frame_on_child () const
 Returns a const reference to the frame M attached on the child body B. More...
 
int velocity_start () const
 Returns the index to the first generalized velocity for this joint within the vector v of generalized velocities for the full multibody system. More...
 
int num_velocities () const
 Returns the number of generalized velocities describing this joint. More...
 
int position_start () const
 Returns the index to the first generalized position for this joint within the vector q of generalized positions for the full multibody system. More...
 
int num_positions () const
 Returns the number of generalized positions describing this joint. More...
 
bool can_rotate () const
 Returns true if this joint's mobility allows relative rotation of the two frames associated with this joint. More...
 
bool can_translate () const
 Returns true if this joint's mobility allows relative translation of the two frames associated with this joint. More...
 
std::string position_suffix (int position_index_in_joint) const
 Returns a string suffix (e.g. More...
 
std::string velocity_suffix (int velocity_index_in_joint) const
 Returns a string suffix (e.g. More...
 
const T & GetOnePosition (const systems::Context< T > &context) const
 Returns the position coordinate for joints with a single degree of freedom. More...
 
const T & GetOneVelocity (const systems::Context< T > &context) const
 Returns the velocity coordinate for joints with a single degree of freedom. More...
 
void AddInOneForce (const systems::Context< T > &context, int joint_dof, const T &joint_tau, MultibodyForces< T > *forces) const
 Adds into forces a force along the one of the joint's degrees of freedom indicated by index joint_dof. More...
 
void AddInDamping (const systems::Context< T > &context, MultibodyForces< T > *forces) const
 Adds into forces the force due to damping within this joint. More...
 
void Lock (systems::Context< T > *context) const
 Lock the joint. More...
 
void Unlock (systems::Context< T > *context) const
 Unlock the joint. More...
 
bool is_locked (const systems::Context< T > &context) const
 
const VectorX< double > & default_damping_vector () const
 Returns all default damping coefficients for joints that model viscous damping, of size num_velocities(). More...
 
const VectorX< double > & damping_vector () const
 (Deprecated.) More...
 
const VectorX< T > & GetDampingVector (const systems::Context< T > &context) const
 Returns the Context dependent damping coefficients stored as parameters in context. More...
 
void set_default_damping_vector (const VectorX< double > &damping)
 Sets the default value of the viscous damping coefficients for this joint. More...
 
void SetDampingVector (systems::Context< T > *context, const VectorX< T > &damping) const
 Sets the value of the viscous damping coefficients for this joint, stored as parameters in context. More...
 
 Joint (const Joint &)=delete
 
Jointoperator= (const Joint &)=delete
 
 Joint (Joint &&)=delete
 
Jointoperator= (Joint &&)=delete
 
const VectorX< double > & position_lower_limits () const
 
const VectorX< double > & position_upper_limits () const
 Returns the position upper limits. More...
 
const VectorX< double > & velocity_lower_limits () const
 Returns the velocity lower limits. More...
 
const VectorX< double > & velocity_upper_limits () const
 Returns the velocity upper limits. More...
 
const VectorX< double > & acceleration_lower_limits () const
 Returns the acceleration lower limits. More...
 
const VectorX< double > & acceleration_upper_limits () const
 Returns the acceleration upper limits. More...
 
const VectorX< double > & default_positions () const
 Returns the default positions. More...
 
void set_position_limits (const VectorX< double > &lower_limits, const VectorX< double > &upper_limits)
 Sets the position limits to lower_limits and upper_limits. More...
 
void set_velocity_limits (const VectorX< double > &lower_limits, const VectorX< double > &upper_limits)
 Sets the velocity limits to lower_limits and upper_limits. More...
 
void set_acceleration_limits (const VectorX< double > &lower_limits, const VectorX< double > &upper_limits)
 Sets the acceleration limits to lower_limits and upper_limits. More...
 
void set_default_positions (const VectorX< double > &default_positions)
 Sets the default positions to default_positions. More...
 
void SetDefaultPose (const math::RigidTransform< double > &X_FM)
 Sets this Joint's default generalized positions q₀ such that the pose of the child frame M in the parent frame F best matches the given pose. More...
 
math::RigidTransform< doubleGetDefaultPose () const
 Returns this Joint's default pose as a RigidTransform X_FM. More...
 
void SetDefaultPosePair (const Quaternion< double > &q_FM, const Vector3< double > &p_FM)
 (Advanced) This is the same as SetDefaultPose() except it takes the pose as a (quaternion, translation vector) pair. More...
 
std::pair< Eigen::Quaternion< double >, Vector3< double > > GetDefaultPosePair () const
 (Advanced) This is the same as GetDefaultPose() except it returns this Joint's default pose as a (quaternion, translation vector) pair. More...
 
- 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
 
MultibodyElementoperator= (const MultibodyElement &)=delete
 
 MultibodyElement (MultibodyElement &&)=delete
 
MultibodyElementoperator= (MultibodyElement &&)=delete
 

Static Public Attributes

static const char kTypeName [] = "revolute"
 

Protected Member Functions

void DoAddInOneForce (const systems::Context< T > &, int joint_dof, const T &joint_tau, MultibodyForces< T > *forces) const override
 Joint<T> override called through public NVI, Joint::AddInForce(). More...
 
void DoAddInDamping (const systems::Context< T > &context, MultibodyForces< T > *forces) const override
 Joint<T> override called through public NVI, Joint::AddInDamping(). More...
 
- Protected Member Functions inherited from Joint< T >
virtual void DoSetDefaultPosePair (const Quaternion< double > &q_FM, const Vector3< double > &p_FM)
 Implementation of the NVI SetDefaultPose(). More...
 
virtual std::pair< Eigen::Quaternion< double >, Vector3< double > > DoGetDefaultPosePair () const
 Implementation of the NVI GetDefaultPose(). More...
 
void DoSetTopology (const internal::MultibodyTreeTopology &) override
 Implementation of the NVI SetTopology(). More...
 
const JointImplementationget_implementation () const
 Returns a const reference to the internal implementation of this joint. More...
 
bool has_implementation () const
 Returns whether this joint owns a particular implementation. 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...
 
 MultibodyElement (ModelInstanceIndex model_instance, int64_t index)
 Both the model instance and element index are specified. 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

template<typename >
class RevoluteJoint
 
class JointTester
 

Member Typedef Documentation

◆ Context

using Context = systems::Context<Scalar>

Constructor & Destructor Documentation

◆ RevoluteJoint() [1/4]

RevoluteJoint ( const RevoluteJoint< T > &  )
delete

◆ RevoluteJoint() [2/4]

RevoluteJoint ( RevoluteJoint< T > &&  )
delete

◆ RevoluteJoint() [3/4]

RevoluteJoint ( const std::string &  name,
const Frame< T > &  frame_on_parent,
const Frame< T > &  frame_on_child,
const Vector3< double > &  axis,
double  damping = 0 
)

Constructor to create a revolute joint between two bodies so that frame F attached to the parent body P and frame M attached to the child body B, rotate relatively to one another about a common axis.

See this class's documentation for further details on the definition of these frames and rotation angle. This constructor signature creates a joint with no joint limits, i.e. the joint position, velocity and acceleration limits are the pair (-∞, ∞). The first three arguments to this constructor are those of the Joint class constructor. See the Joint class's documentation for details. The additional parameters are:

Parameters
[in]axisA vector in ℝ³ specifying the axis of revolution for this joint. Given that frame M only rotates with respect to F and their origins are coincident at all times, the measures of axis in either frame F or M are exactly the same, that is, axis_F = axis_M. In other words, axis_F (or axis_M) is the eigenvector of R_FM with eigenvalue equal to one. This vector can have any length, only the direction is used. This method aborts if axis is the zero vector.
[in]dampingViscous damping coefficient, in N⋅m⋅s, used to model losses within the joint. The damping torque (in N⋅m) is modeled as τ = -damping⋅ω, i.e. opposing motion, with ω the angular rate for this joint (see get_angular_rate()).
Exceptions
std::exceptionif damping is negative.

◆ RevoluteJoint() [4/4]

RevoluteJoint ( const std::string &  name,
const Frame< T > &  frame_on_parent,
const Frame< T > &  frame_on_child,
const Vector3< double > &  axis,
double  pos_lower_limit,
double  pos_upper_limit,
double  damping = 0 
)

Constructor to create a revolute joint between two bodies so that frame F attached to the parent body P and frame M attached to the child body B, rotate relatively to one another about a common axis.

See this class's documentation for further details on the definition of these frames and rotation angle. The first three arguments to this constructor are those of the Joint class constructor. See the Joint class's documentation for details. The additional parameters are:

Parameters
[in]axisA vector in ℝ³ specifying the axis of revolution for this joint. Given that frame M only rotates with respect to F and their origins are coincident at all times, the measures of axis in either frame F or M are exactly the same, that is, axis_F = axis_M. In other words, axis_F (or axis_M) is the eigenvector of R_FM with eigenvalue equal to one. This vector can have any length, only the direction is used.
[in]pos_lower_limitLower position limit, in radians, for the rotation coordinate (see get_angle()).
[in]pos_upper_limitUpper position limit, in radians, for the rotation coordinate (see get_angle()).
[in]dampingViscous damping coefficient, in N⋅m⋅s, used to model losses within the joint. The damping torque (in N⋅m) is modeled as τ = -damping⋅ω, i.e. opposing motion, with ω the angular rate for this joint (see get_angular_rate()).
Exceptions
std::exceptionif the L2 norm of axis is less than the square root of machine epsilon.
std::exceptionif damping is negative.
std::exceptionif pos_lower_limit > pos_upper_limit.

Member Function Documentation

◆ acceleration_lower_limit()

double acceleration_lower_limit ( ) const

Returns the acceleration lower limit for this joint in radians / s².

◆ acceleration_upper_limit()

double acceleration_upper_limit ( ) const

Returns the acceleration upper limit for this joint in radians / s².

◆ AddInTorque()

void AddInTorque ( const systems::Context< T > &  context,
const T &  torque,
MultibodyForces< T > *  forces 
) const

Adds into forces a given torque for this joint that is to be applied about the joint's axis.

The torque is defined to be positive according to the right-hand-rule with the thumb aligned in the direction of this joint's axis. That is, a positive torque causes a positive rotational acceleration according to the right-hand-rule around the joint's axis.

Note
A torque is the moment of a set of forces whose resultant is zero.

◆ damping()

double damping ( ) const

(Deprecated.)

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

◆ default_damping()

double default_damping ( ) const

Returns this joint's default damping constant in N⋅m⋅s.

◆ DoAddInDamping()

void DoAddInDamping ( const systems::Context< T > &  context,
MultibodyForces< T > *  forces 
) const
overrideprotectedvirtual

Joint<T> override called through public NVI, Joint::AddInDamping().

Therefore arguments were already checked to be valid. This method adds into forces a dissipative torque according to the viscous law τ = -d⋅ω, with d the damping coefficient (see default_damping()).

Reimplemented from Joint< T >.

◆ DoAddInOneForce()

void DoAddInOneForce ( const systems::Context< T > &  ,
int  joint_dof,
const T &  joint_tau,
MultibodyForces< T > *  forces 
) const
overrideprotectedvirtual

Joint<T> override called through public NVI, Joint::AddInForce().

Therefore arguments were already checked to be valid. For a RevoluteJoint, we must always have joint_dof = 0 since there is only a single degree of freedom (num_velocities() == 1). joint_tau is the torque applied about the joint's axis, on the body declared as child (according to the revolute joint's constructor) at the origin of the child frame (which is coincident with the origin of the parent frame at all times). The torque is defined to be positive according to the right-hand-rule with the thumb aligned in the direction of this joint's axis. That is, a positive torque causes a positive rotational acceleration (of the child body frame) according to the right-hand-rule around the joint's axis.

Implements Joint< T >.

◆ get_angle()

const T& get_angle ( const Context< T > &  context) const

Gets the rotation angle of this mobilizer from context.

Parameters
[in]contextThe context of the MultibodyTree this joint belongs to.
Returns
The angle coordinate of this joint stored in the context.

◆ get_angular_rate()

const T& get_angular_rate ( const Context< T > &  context) const

Gets the rate of change, in radians per second, of this joint's angle (see get_angle()) from context.

Parameters
[in]contextThe context of the MultibodyTree this joint belongs to.
Returns
The rate of change of this joint's angle as stored in the context.

◆ get_default_angle()

double get_default_angle ( ) const

Gets the default rotation angle.

Wrapper for the more general Joint::default_positions().

Returns
The default angle of this stored in default_positions_

◆ GetDamping()

const T& GetDamping ( const Context< T > &  context) const

Returns the Context dependent damping coefficient stored as a parameter in context.

Refer to default_damping() for details.

Parameters
[in]contextThe context storing the state and parameters for the model to which this joint belongs.

◆ operator=() [1/2]

RevoluteJoint& operator= ( const RevoluteJoint< T > &  )
delete

◆ operator=() [2/2]

RevoluteJoint& operator= ( RevoluteJoint< T > &&  )
delete

◆ position_lower_limit()

double position_lower_limit ( ) const

Returns the position lower limit for this joint in radians.

◆ position_upper_limit()

double position_upper_limit ( ) const

Returns the position upper limit for this joint in radians.

◆ revolute_axis()

const Vector3<double>& revolute_axis ( ) const

Returns the axis of revolution of this joint as a unit vector.

Since the measures of this axis in either frame F or M are the same (see this class's documentation for frame definitions) then, axis = axis_F = axis_M.

◆ set_angle()

const RevoluteJoint<T>& set_angle ( Context< T > *  context,
const T &  angle 
) const

Sets the context so that the generalized coordinate corresponding to the rotation angle of this joint equals angle.

Parameters
[in]contextThe context of the MultibodyTree this joint belongs to.
[in]angleThe desired angle in radians to be stored in context.
Returns
a constant reference to this joint.

◆ set_angular_rate()

const RevoluteJoint<T>& set_angular_rate ( Context< T > *  context,
const T &  angle 
) const

Sets the rate of change, in radians per second, of this this joint's angle to theta_dot.

The new rate of change theta_dot gets stored in context.

Parameters
[in]contextThe context of the MultibodyTree this joint belongs to.
[in]theta_dotThe desired rate of change of this joints's angle in radians per second.
Returns
a constant reference to this joint.

◆ set_default_angle()

void set_default_angle ( double  angle)

Sets the default_positions of this joint (in this case a single angle).

Parameters
[in]angleThe desired default angle of the joint

◆ set_default_damping()

void set_default_damping ( double  damping)

Sets the default value of viscous damping for this joint, in N⋅m⋅s.

Exceptions
std::exceptionif damping is negative.
Precondition
the MultibodyPlant must not be finalized.

◆ set_random_angle_distribution()

void set_random_angle_distribution ( const symbolic::Expression angle)

◆ SetDamping()

void SetDamping ( Context< T > *  context,
const T &  damping 
) const

Sets the value of the viscous damping coefficient for this joint, stored as a parameter in context.

Refer to default_damping() for details.

Parameters
[out]contextThe context storing the state and parameters for the model to which this joint belongs.
[in]dampingThe damping value.
Exceptions
std::exceptionif damping is negative.

◆ type_name()

const std::string& type_name ( ) const
overridevirtual

Returns a string identifying the type of this joint, such as "revolute" or "prismatic".

Implements Joint< T >.

◆ velocity_lower_limit()

double velocity_lower_limit ( ) const

Returns the velocity lower limit for this joint in radians / s.

◆ velocity_upper_limit()

double velocity_upper_limit ( ) const

Returns the velocity upper limit for this joint in radians / s.

Friends And Related Function Documentation

◆ JointTester

friend class JointTester
friend

◆ RevoluteJoint

friend class RevoluteJoint
friend

Member Data Documentation

◆ kTypeName

const char kTypeName = "revolute"
static

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