diff --git a/multibody/plant/images/BodyParentChildJoint.png b/multibody/plant/images/BodyParentChildJoint.png new file mode 100755 index 000000000000..a72dfdaf885c Binary files /dev/null and b/multibody/plant/images/BodyParentChildJoint.png differ diff --git a/multibody/plant/images/BodyParentChildJoint.txt b/multibody/plant/images/BodyParentChildJoint.txt new file mode 100755 index 000000000000..335704d71dc8 --- /dev/null +++ b/multibody/plant/images/BodyParentChildJoint.txt @@ -0,0 +1,3 @@ +The graphics file BodyParentChildJoint.png was created by Canvas X +(commercial PC/Windows technical illustration program). Raster graphics (PNG) +was chosen over vector graphics (SVG) because it better rendered the fonts. diff --git a/multibody/plant/images/BodyParentChildJointCM.png b/multibody/plant/images/BodyParentChildJointCM.png new file mode 100755 index 000000000000..122636f5bd08 Binary files /dev/null and b/multibody/plant/images/BodyParentChildJointCM.png differ diff --git a/multibody/plant/images/BodyParentChildJointCM.txt b/multibody/plant/images/BodyParentChildJointCM.txt new file mode 100755 index 000000000000..9b6efeab3c4a --- /dev/null +++ b/multibody/plant/images/BodyParentChildJointCM.txt @@ -0,0 +1,3 @@ +The graphics file BodyParentChildJointCM.png was created by Canvas X +(commercial PC/Windows technical illustration program). Raster graphics (PNG) +was chosen over vector graphics (SVG) because it better rendered the fonts. diff --git a/multibody/plant/multibody_plant.h b/multibody/plant/multibody_plant.h index b7fd2a47f863..6245ed79161a 100644 --- a/multibody/plant/multibody_plant.h +++ b/multibody/plant/multibody_plant.h @@ -888,8 +888,7 @@ class MultibodyPlant : public internal::MultibodyTreeSystem { } /// This method adds a Joint of type `JointType` between two bodies. - /// For more information, see the below overload of `AddJoint<>`, and the - /// related `MultibodyTree::AddJoint<>` method. + /// For more information, see the below overload of `AddJoint<>`. template class JointType> const JointType& AddJoint(std::unique_ptr> joint) { DRAKE_MBP_THROW_IF_FINALIZED(); @@ -900,12 +899,14 @@ class MultibodyPlant : public internal::MultibodyTreeSystem { } /// This method adds a Joint of type `JointType` between two bodies. - /// The two bodies connected by this Joint object are referred to as the - /// _parent_ and _child_ bodies. Although the terms _parent_ and _child_ are - /// sometimes used synonymously to describe the relationship between inboard - /// and outboard bodies in multibody models, this usage is wholly unrelated - /// and implies nothing about the inboard-outboard relationship between the - /// bodies. + /// The two bodies connected by this Joint object are referred to as _parent_ + /// and _child_ bodies. The parent/child ordering defines the sign conventions + /// for the generalized coordinates and the coordinate ordering for multi-DOF + /// joints. + /// @image html multibody/plant/images/BodyParentChildJointCM.png width=50% + /// Note: The previous figure also shows Pcm which is body P's center of mass + /// and point Bcm which is body B's center of mass. + /// /// As explained in the Joint class's documentation, in Drake we define a /// frame F attached to the parent body P with pose `X_PF` and a frame M /// attached to the child body B with pose `X_BM`. This method helps creating @@ -977,6 +978,8 @@ class MultibodyPlant : public internal::MultibodyTreeSystem { const std::optional>& X_PF, const Body& child, const std::optional>& X_BM, Args&&... args) { + // TODO(Mitiguy) Per discussion in PR# 13961 and issues #12789 and #13040, + // consider changing frame F to frame Jp and changing frame M to frame Jc. static_assert(std::is_base_of, JointType>::value, "JointType must be a sub-class of Joint."); diff --git a/multibody/tree/joint.h b/multibody/tree/joint.h index abe7a6b13b33..01f5bf1e049e 100644 --- a/multibody/tree/joint.h +++ b/multibody/tree/joint.h @@ -20,16 +20,14 @@ namespace multibody { /// A %Joint models the kinematical relationship which characterizes the /// possible relative motion between two bodies. -/// The two bodies connected by a %Joint object are referred to as the -/// _parent_ and _child_ bodies. Although the terms _parent_ and _child_ are -/// sometimes used synonymously to describe the relationship between inboard and -/// outboard bodies in multibody _trees_, the parent/child relationship is -/// more general and remains meaningful for multibody systems with loops, such -/// as a four-bar linkage. However, whenever possible the parent body will be -/// made to be inboard and the child outboard in the tree. +/// The two bodies connected by this %Joint object are referred to as _parent_ +/// and _child_ bodies. The parent/child ordering defines the sign conventions +/// for the generalized coordinates and the coordinate ordering for multi-DOF +/// joints. /// A %Joint is a model of a physical kinematic constraint between two bodies, /// a constraint that in the real physical system does not specify a tree /// ordering. +/// @image html multibody/plant/images/BodyParentChildJoint.png width=50% /// /// In Drake we define a frame F rigidly attached to the parent body P with pose /// `X_PF` and a frame M rigidly attached to the child body B with pose `X_BM`. @@ -128,6 +126,8 @@ class Joint : public MultibodyElement { vel_upper_limits_(vel_upper_limits), acc_lower_limits_(acc_lower_limits), acc_upper_limits_(acc_upper_limits) { + // TODO(Mitiguy) Per discussion in PR# 13961 and issues #12789 and #13040, + // consider changing frame F to frame Jp and changing frame M to frame Jc. // Notice `this` joint references `frame_on_parent` and `frame_on_child` and // therefore they must outlive it. DRAKE_DEMAND(pos_lower_limits.size() == pos_upper_limits.size()); diff --git a/multibody/tree/multibody_tree.h b/multibody/tree/multibody_tree.h index bcb0698789e7..bdc80dac69e0 100644 --- a/multibody/tree/multibody_tree.h +++ b/multibody/tree/multibody_tree.h @@ -413,14 +413,16 @@ class MultibodyTree { const JointType& AddJoint( std::unique_ptr> joint); - /// This method helps to create a Joint of type `JointType` between two - /// bodies. - /// The two bodies connected by this Joint object are referred to as the - /// _parent_ and _child_ bodies. Although the terms _parent_ and _child_ are - /// sometimes used synonymously to describe the relationship between inboard - /// and outboard bodies in multibody models, this usage is wholly unrelated - /// and implies nothing about the inboard-outboard relationship between the - /// bodies. + /// This method adds a Joint of type `JointType` between two bodies. + /// The two bodies connected by this Joint object are referred to as _parent_ + /// and _child_ bodies. The parent/child ordering defines the sign conventions + /// for the generalized coordinates and the coordinate ordering for multi-DOF + /// joints. Our use of the terms _parent_ and _child_ does 𝐧𝐨𝐭 describe the + /// inboard/outboard relationship between bodies as our usage of inboard/ + /// outboard is more general and is also meaningful for multibody systems + /// with loops, such as four-bar linkages. However, when possible the + /// _parent_ body is made inboard and the _child_ outboard in the tree. + /// /// As explained in the Joint class's documentation, in Drake we define a /// frame F attached to the parent body P with pose `X_PF` and a frame M /// attached to the child body B with pose `X_BM`. This method helps create