1 #ifndef SimTK_SIMBODY_MOBILIZED_BODY_LINEORIENTATION_H_ 2 #define SimTK_SIMBODY_MOBILIZED_BODY_LINEORIENTATION_H_ 3 4 /* -------------------------------------------------------------------------- * 5 * Simbody(tm) * 6 * -------------------------------------------------------------------------- * 7 * This is part of the SimTK biosimulation toolkit originating from * 8 * Simbios, the NIH National Center for Physics-Based Simulation of * 9 * Biological Structures at Stanford, funded under the NIH Roadmap for * 10 * Medical Research, grant U54 GM072970. See https://simtk.org/home/simbody. * 11 * * 12 * Portions copyright (c) 2007-13 Stanford University and the Authors. * 13 * Authors: Michael Sherman * 14 * Contributors: Paul Mitiguy * 15 * * 16 * Licensed under the Apache License, Version 2.0 (the "License"); you may * 17 * not use this file except in compliance with the License. You may obtain a * 18 * copy of the License at http://www.apache.org/licenses/LICENSE-2.0. * 19 * * 20 * Unless required by applicable law or agreed to in writing, software * 21 * distributed under the License is distributed on an "AS IS" BASIS, * 22 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. * 23 * See the License for the specific language governing permissions and * 24 * limitations under the License. * 25 * -------------------------------------------------------------------------- */ 26 27 /** @file 28 Declares the MobilizedBody::LineOrientation class. **/ 29 30 #include "simbody/internal/MobilizedBody.h" 31 32 namespace SimTK { 33 34 /** Two mobilities, representing unrestricted orientation for a body which is 35 inertialess along its own z axis. The generalized coordinates are the same 36 as for the general Ball (Spherical) mobilizer, but there are only 37 two generalized speeds. These are the x,y components of the angular velocity 38 of frame M in F, but expressed in \e M (the body or outboard frame). 39 40 LineOrientation and FreeLine are special "ball" and "free" mobilizers designed 41 to allow arbitrary orientations for "linear" bodies, such as a CO2 molecule 42 consisting only of point masses arranged along a straight line. Such bodies have 43 no inertia about the line and cause singularities in the equations of motion if 44 attached to Ball (Spherical) or Free mobilizers. Instead, use the 45 LineOrientation and LineFree mobilizers, making sure that the inertialess 46 direction is along the outboard body's z axis (that is, Mz). These mobilizers 47 introduce only two rotational mobilities (generalized speeds u), being incapable 48 of representing non-zero angular velocity of M in F about Mz. The generalized 49 speeds are in fact the wx and wy components of w_FM_M, that is, the x and y 50 components of the angular velocity of M in F <em>expressed in M</em>. However, 51 at least three generalized coordinates (q's) are required to represent the 52 orientation. By default we use four quaternions for unconditional stability. 53 Alternatively, you can request a 1-2-3 body fixed Euler angle sequence (that is, 54 about x, then new y, then new z) which will suffer a singularity when the y 55 rotation is 90 degrees since that aligns the first rotation axis (x) with the 56 last (z) which is the inertialess direction. 57 58 @see MobilizedBody::FreeLine, MobilizedBody::Ball **/ 59 class SimTK_SIMBODY_EXPORT MobilizedBody::LineOrientation : public MobilizedBody { 60 public: 61 /** Default constructor provides an empty handle that can be assigned to 62 reference any %MobilizedBody::LineOrientation. **/ LineOrientation()63 LineOrientation() {} 64 65 /** Create a %LineOrientation mobilizer between an existing parent (inboard) 66 body P and a new child (outboard) body B created by copying the given 67 \a bodyInfo into a privately-owned Body within the constructed 68 %MobilizedBody object. Specify the mobilizer frames F fixed to parent P and 69 M fixed to child B. 70 @see MobilizedBody for a diagram and explanation of terminology. **/ 71 LineOrientation(MobilizedBody& parent, const Transform& X_PF, 72 const Body& bodyInfo, const Transform& X_BM, 73 Direction=Forward); 74 75 /** Abbreviated constructor you can use if the mobilizer frames are 76 coincident with the parent and child body frames. **/ 77 LineOrientation(MobilizedBody& parent, const Body& bodyInfo, 78 Direction=Forward); 79 addBodyDecoration(const Transform & X_BD,const DecorativeGeometry & g)80 LineOrientation& addBodyDecoration(const Transform& X_BD, const DecorativeGeometry& g) { 81 (void)MobilizedBody::addBodyDecoration(X_BD,g); return *this; 82 } addOutboardDecoration(const Transform & X_MD,const DecorativeGeometry & g)83 LineOrientation& addOutboardDecoration(const Transform& X_MD, const DecorativeGeometry& g) { 84 (void)MobilizedBody::addOutboardDecoration(X_MD,g); return *this; 85 } addInboardDecoration(const Transform & X_FD,const DecorativeGeometry & g)86 LineOrientation& addInboardDecoration (const Transform& X_FD, const DecorativeGeometry& g) { 87 (void)MobilizedBody::addInboardDecoration(X_FD,g); return *this; 88 } 89 setDefaultInboardFrame(const Transform & X_PF)90 LineOrientation& setDefaultInboardFrame(const Transform& X_PF) { 91 (void)MobilizedBody::setDefaultInboardFrame(X_PF); return *this; 92 } 93 setDefaultOutboardFrame(const Transform & X_BM)94 LineOrientation& setDefaultOutboardFrame(const Transform& X_BM) { 95 (void)MobilizedBody::setDefaultOutboardFrame(X_BM); return *this; 96 } 97 98 // This is just a nicer name for the generalized coordinate. setDefaultRotation(const Rotation & R_FM)99 LineOrientation& setDefaultRotation(const Rotation& R_FM) { 100 return setDefaultQ(R_FM.convertRotationToQuaternion()); 101 } getDefaultRotation()102 Rotation getDefaultRotation() const {return Rotation(getDefaultQ());} 103 104 // Generic default state Topology methods. 105 const Quaternion& getDefaultQ() const; 106 LineOrientation& setDefaultQ(const Quaternion& q); 107 108 const Vec4& getQ(const State&) const; 109 const Vec4& getQDot(const State&) const; 110 const Vec4& getQDotDot(const State&) const; 111 const Vec2& getU(const State&) const; 112 const Vec2& getUDot(const State&) const; 113 114 void setQ(State&, const Vec4&) const; 115 void setU(State&, const Vec2&) const; 116 117 const Vec4& getMyPartQ(const State&, const Vector& qlike) const; 118 const Vec2& getMyPartU(const State&, const Vector& ulike) const; 119 120 Vec4& updMyPartQ(const State&, Vector& qlike) const; 121 Vec2& updMyPartU(const State&, Vector& ulike) const; 122 123 /** @cond **/ // hide from Doxygen 124 SimTK_INSERT_DERIVED_HANDLE_DECLARATIONS(LineOrientation, 125 LineOrientationImpl, MobilizedBody); 126 /** @endcond **/ 127 }; 128 129 } // namespace SimTK 130 131 #endif // SimTK_SIMBODY_MOBILIZED_BODY_LINEORIENTATION_H_ 132 133 134 135