CLHEP VERSION Reference Documentation
CLHEP Home Page CLHEP Documentation CLHEP Bug Reports |
00001 // -*- C++ -*- 00002 // CLASSDOC OFF 00003 // $Id: Rotation.h,v 1.3 2003/10/23 21:29:52 garren Exp $ 00004 // --------------------------------------------------------------------------- 00005 // CLASSDOC ON 00006 // 00007 // This file is a part of the CLHEP - a Class Library for High Energy Physics. 00008 // 00009 // This is the definition of the HepRotation class for performing rotations 00010 // on objects of the Hep3Vector (and HepLorentzVector) class. 00011 // 00012 // HepRotation is a concrete implementation of Hep3RotationInterface. 00013 // 00014 // .SS See Also 00015 // RotationInterfaces.h 00016 // ThreeVector.h, LorentzVector.h, LorentzRotation.h 00017 // 00018 // .SS Author 00019 // Leif Lonnblad, Mark Fischler 00020 00021 #ifndef HEP_ROTATION_H 00022 #define HEP_ROTATION_H 00023 00024 #ifdef GNUPRAGMA 00025 #pragma interface 00026 #endif 00027 00028 #include "CLHEP/Vector/defs.h" 00029 #include "CLHEP/Vector/RotationInterfaces.h" 00030 #include "CLHEP/Vector/RotationX.h" 00031 #include "CLHEP/Vector/RotationY.h" 00032 #include "CLHEP/Vector/RotationZ.h" 00033 #include "CLHEP/Vector/LorentzVector.h" 00034 00035 namespace CLHEP { 00036 00037 // Declarations of classes and global methods 00038 class HepRotation; 00039 inline HepRotation inverseOf ( const HepRotation & r ); 00040 inline HepRotation operator * (const HepRotationX & rx, const HepRotation & r); 00041 inline HepRotation operator * (const HepRotationY & ry, const HepRotation & r); 00042 inline HepRotation operator * (const HepRotationZ & rz, const HepRotation & r); 00043 00048 class HepRotation { 00049 00050 public: 00051 00052 // ---------- Constructors and Assignment: 00053 00054 inline HepRotation(); 00055 // Default constructor. Gives a unit matrix. 00056 00057 inline HepRotation(const HepRotation & m); 00058 // Copy constructor. 00059 00060 inline HepRotation(const HepRotationX & m); 00061 inline HepRotation(const HepRotationY & m); 00062 inline HepRotation(const HepRotationZ & m); 00063 // Construct from specialized rotation. 00064 00065 HepRotation & set( const Hep3Vector & axis, double delta ); 00066 HepRotation ( const Hep3Vector & axis, double delta ); 00067 // Construct from axis and angle. 00068 00069 HepRotation & set( const HepAxisAngle & ax ); 00070 HepRotation ( const HepAxisAngle & ax ); 00071 // Construct from AxisAngle structure. 00072 00073 HepRotation & set( double phi, double theta, double psi ); 00074 HepRotation ( double phi, double theta, double psi ); 00075 // Construct from three Euler angles (in radians). 00076 00077 HepRotation & set( const HepEulerAngles & e ); 00078 HepRotation ( const HepEulerAngles & e ); 00079 // Construct from EulerAngles structure. 00080 00081 HepRotation ( const Hep3Vector & colX, 00082 const Hep3Vector & colY, 00083 const Hep3Vector & colZ ); 00084 // Construct from three *orthogonal* unit vector columns. 00085 // NOTE: 00086 // This constructor, and the two set methods below, 00087 // will check that the columns (or rows) form an orthonormal 00088 // matrix, and will adjust values so that this relation is 00089 // as exact as possible. 00090 00091 HepRotation & set( const Hep3Vector & colX, 00092 const Hep3Vector & colY, 00093 const Hep3Vector & colZ ); 00094 // supply three *orthogonal* unit vectors for the columns. 00095 00096 HepRotation & setRows( const Hep3Vector & rowX, 00097 const Hep3Vector & rowY, 00098 const Hep3Vector & rowZ ); 00099 // supply three *orthogonal* unit vectors for the rows. 00100 00101 inline HepRotation & set(const HepRotationX & r); 00102 inline HepRotation & set(const HepRotationY & r); 00103 inline HepRotation & set(const HepRotationZ & r); 00104 // set from specialized rotation. 00105 00106 inline HepRotation & operator = (const HepRotation & r); 00107 // Assignment. 00108 00109 inline HepRotation & operator = (const HepRotationX & r); 00110 inline HepRotation & operator = (const HepRotationY & r); 00111 inline HepRotation & operator = (const HepRotationZ & r); 00112 // Assignment from specialized rotation. 00113 00114 inline HepRotation &set( const HepRep3x3 & m ); 00115 inline HepRotation ( const HepRep3x3 & m ); 00116 // WARNING - NO CHECKING IS DONE! 00117 // Constructon directly from from a 3x3 representation, 00118 // which is required to be an orthogonal matrix. 00119 00120 inline ~HepRotation(); 00121 // Trivial destructor. 00122 00123 // ---------- Accessors: 00124 00125 inline Hep3Vector colX() const; 00126 inline Hep3Vector colY() const; 00127 inline Hep3Vector colZ() const; 00128 // orthogonal unit-length column vectors 00129 00130 inline Hep3Vector rowX() const; 00131 inline Hep3Vector rowY() const; 00132 inline Hep3Vector rowZ() const; 00133 // orthogonal unit-length row vectors 00134 00135 inline double xx() const; 00136 inline double xy() const; 00137 inline double xz() const; 00138 inline double yx() const; 00139 inline double yy() const; 00140 inline double yz() const; 00141 inline double zx() const; 00142 inline double zy() const; 00143 inline double zz() const; 00144 // Elements of the rotation matrix (Geant4). 00145 00146 inline HepRep3x3 rep3x3() const; 00147 // 3x3 representation: 00148 00149 // ------------ Subscripting: 00150 00151 class HepRotation_row { 00152 public: 00153 inline HepRotation_row(const HepRotation &, int); 00154 inline double operator [] (int) const; 00155 private: 00156 const HepRotation & rr; 00157 int ii; 00158 }; 00159 // Helper class for implemention of C-style subscripting r[i][j] 00160 00161 inline const HepRotation_row operator [] (int) const; 00162 // Returns object of the helper class for C-style subscripting r[i][j] 00163 // i and j range from 0 to 2. 00164 00165 double operator () (int, int) const; 00166 // Fortran-style subscripting: returns (i,j) element of the rotation matrix. 00167 // Note: i and j still range from 0 to 2. [Rotation.cc] 00168 00169 // ------------ Euler angles: 00170 inline double getPhi () const; 00171 inline double getTheta() const; 00172 inline double getPsi () const; 00173 double phi () const; 00174 double theta() const; 00175 double psi () const; 00176 HepEulerAngles eulerAngles() const; 00177 00178 // ------------ axis & angle of rotation: 00179 inline double getDelta() const; 00180 inline Hep3Vector getAxis () const; 00181 double delta() const; 00182 Hep3Vector axis () const; 00183 HepAxisAngle axisAngle() const; 00184 void getAngleAxis(double & delta, Hep3Vector & axis) const; 00185 // Returns the rotation angle and rotation axis (Geant4). [Rotation.cc] 00186 00187 // ------------- Angles of rotated axes 00188 double phiX() const; 00189 double phiY() const; 00190 double phiZ() const; 00191 double thetaX() const; 00192 double thetaY() const; 00193 double thetaZ() const; 00194 // Return angles (RADS) made by rotated axes against original axes (Geant4). 00195 // [Rotation.cc] 00196 00197 // ---------- Other accessors treating pure rotation as a 4-rotation 00198 00199 inline HepLorentzVector col1() const; 00200 inline HepLorentzVector col2() const; 00201 inline HepLorentzVector col3() const; 00202 // orthosymplectic 4-vector columns - T component will be zero 00203 00204 inline HepLorentzVector col4() const; 00205 // Will be (0,0,0,1) for this pure Rotation. 00206 00207 inline HepLorentzVector row1() const; 00208 inline HepLorentzVector row2() const; 00209 inline HepLorentzVector row3() const; 00210 // orthosymplectic 4-vector rows - T component will be zero 00211 00212 inline HepLorentzVector row4() const; 00213 // Will be (0,0,0,1) for this pure Rotation. 00214 00215 inline double xt() const; 00216 inline double yt() const; 00217 inline double zt() const; 00218 inline double tx() const; 00219 inline double ty() const; 00220 inline double tz() const; 00221 // Will be zero for this pure Rotation 00222 00223 inline double tt() const; 00224 // Will be one for this pure Rotation 00225 00226 inline HepRep4x4 rep4x4() const; 00227 // 4x4 representation. 00228 00229 // --------- Mutators 00230 00231 void setPhi (double phi); 00232 // change Euler angle phi, leaving theta and psi unchanged. 00233 00234 void setTheta (double theta); 00235 // change Euler angle theta, leaving phi and psi unchanged. 00236 00237 void setPsi (double psi); 00238 // change Euler angle psi, leaving theta and phi unchanged. 00239 00240 void setAxis (const Hep3Vector & axis); 00241 // change rotation axis, leaving delta unchanged. 00242 00243 void setDelta (double delta); 00244 // change angle of rotation, leaving rotation axis unchanged. 00245 00246 // ---------- Decomposition: 00247 00248 void decompose (HepAxisAngle & rotation, Hep3Vector & boost) const; 00249 void decompose (Hep3Vector & boost, HepAxisAngle & rotation) const; 00250 // These are trivial, as the boost vector is 0. [RotationP.cc] 00251 00252 // ---------- Comparisons: 00253 00254 bool isIdentity() const; 00255 // Returns true if the identity matrix (Geant4). [Rotation.cc] 00256 00257 int compare( const HepRotation & r ) const; 00258 // Dictionary-order comparison, in order zz, zy, zx, yz, ... xx 00259 // Used in operator<, >, <=, >= 00260 00261 inline bool operator== ( const HepRotation & r ) const; 00262 inline bool operator!= ( const HepRotation & r ) const; 00263 inline bool operator< ( const HepRotation & r ) const; 00264 inline bool operator> ( const HepRotation & r ) const; 00265 inline bool operator<= ( const HepRotation & r ) const; 00266 inline bool operator>= ( const HepRotation & r ) const; 00267 00268 double distance2( const HepRotation & r ) const; 00269 // 3 - Tr ( this/r ) -- This works with RotationX, Y or Z also 00270 00271 double howNear( const HepRotation & r ) const; 00272 bool isNear( const HepRotation & r, 00273 double epsilon=Hep4RotationInterface::tolerance) const; 00274 00275 double distance2( const HepBoost & lt ) const; 00276 // 3 - Tr ( this ) + |b|^2 / (1-|b|^2) 00277 double distance2( const HepLorentzRotation & lt ) const; 00278 // 3 - Tr ( this/r ) + |b|^2 / (1-|b|^2) where b is the boost vector of lt 00279 00280 double howNear( const HepBoost & lt ) const; 00281 double howNear( const HepLorentzRotation & lt ) const; 00282 bool isNear( const HepBoost & lt, 00283 double epsilon=Hep4RotationInterface::tolerance) const; 00284 bool isNear( const HepLorentzRotation & lt, 00285 double epsilon=Hep4RotationInterface::tolerance) const; 00286 00287 // ---------- Properties: 00288 00289 double norm2() const; 00290 // distance2 (IDENTITY), which is 3 - Tr ( *this ) 00291 00292 void rectify(); 00293 // non-const but logically moot correction for accumulated roundoff errors 00294 // rectify averages the matrix with the transpose of its actual 00295 // inverse (absent accumulated roundoff errors, the transpose IS 00296 // the inverse)); this removes to first order those errors. 00297 // Then it formally extracts axis and delta, and forms a true 00298 // HepRotation with those values of axis and delta. 00299 00300 // ---------- Application: 00301 00302 inline Hep3Vector operator() (const Hep3Vector & p) const; 00303 // Rotate a Hep3Vector. 00304 00305 inline Hep3Vector operator * (const Hep3Vector & p) const; 00306 // Multiplication with a Hep3Vector. 00307 00308 inline HepLorentzVector operator()( const HepLorentzVector & w ) const; 00309 // Rotate (the space part of) a HepLorentzVector. 00310 00311 inline HepLorentzVector operator* ( const HepLorentzVector & w ) const; 00312 // Multiplication with a HepLorentzVector. 00313 00314 // ---------- Operations in the group of Rotations 00315 00316 inline HepRotation operator * (const HepRotation & r) const; 00317 // Product of two rotations (this) * r - matrix multiplication 00318 00319 inline HepRotation operator * (const HepRotationX & rx) const; 00320 inline HepRotation operator * (const HepRotationY & ry) const; 00321 inline HepRotation operator * (const HepRotationZ & rz) const; 00322 // Product of two rotations (this) * r - faster when specialized type 00323 00324 inline HepRotation & operator *= (const HepRotation & r); 00325 inline HepRotation & transform (const HepRotation & r); 00326 // Matrix multiplication. 00327 // Note a *= b; <=> a = a * b; while a.transform(b); <=> a = b * a; 00328 00329 inline HepRotation & operator *= (const HepRotationX & r); 00330 inline HepRotation & operator *= (const HepRotationY & r); 00331 inline HepRotation & operator *= (const HepRotationZ & r); 00332 inline HepRotation & transform (const HepRotationX & r); 00333 inline HepRotation & transform (const HepRotationY & r); 00334 inline HepRotation & transform (const HepRotationZ & r); 00335 // Matrix multiplication by specialized matrices 00336 00337 HepRotation & rotateX(double delta); 00338 // Rotation around the x-axis; equivalent to R = RotationX(delta) * R 00339 00340 HepRotation & rotateY(double delta); 00341 // Rotation around the y-axis; equivalent to R = RotationY(delta) * R 00342 00343 HepRotation & rotateZ(double delta); 00344 // Rotation around the z-axis; equivalent to R = RotationZ(delta) * R 00345 00346 HepRotation & rotate(double delta, const Hep3Vector & axis); 00347 inline HepRotation & rotate(double delta, const Hep3Vector * axis); 00348 // Rotation around a specified vector. 00349 // r.rotate(d,a) is equivalent to r = Rotation(d,a) * r 00350 00351 HepRotation & rotateAxes(const Hep3Vector & newX, 00352 const Hep3Vector & newY, 00353 const Hep3Vector & newZ); 00354 // Rotation of local axes defined by 3 orthonormal vectors (Geant4). 00355 // Equivalent to r = Rotation (newX, newY, newZ) * r 00356 00357 inline HepRotation inverse() const; 00358 // Returns the inverse. 00359 00360 inline HepRotation & invert(); 00361 // Inverts the Rotation matrix. 00362 00363 // ---------- I/O: 00364 00365 std::ostream & print( std::ostream & os ) const; 00366 // Aligned six-digit-accurate output of the rotation matrix. [RotationIO.cc] 00367 00368 // ---------- Identity Rotation: 00369 00370 static const HepRotation IDENTITY; 00371 00372 // ---------- Tolerance 00373 00374 static inline double getTolerance(); 00375 static inline double setTolerance(double tol); 00376 00377 protected: 00378 00379 inline HepRotation(double mxx, double mxy, double mxz, 00380 double myx, double myy, double myz, 00381 double mzx, double mzy, double mzz); 00382 // Protected constructor. 00383 // DOES NOT CHECK FOR VALIDITY AS A ROTATION. 00384 00385 friend HepRotation operator* (const HepRotationX & rx, const HepRotation & r); 00386 friend HepRotation operator* (const HepRotationY & ry, const HepRotation & r); 00387 friend HepRotation operator* (const HepRotationZ & rz, const HepRotation & r); 00388 00389 double rxx, rxy, rxz, 00390 ryx, ryy, ryz, 00391 rzx, rzy, rzz; 00392 // The matrix elements. 00393 00394 private: 00395 bool 00396 setCols ( const Hep3Vector & u1, // Vectors assume to be of unit length 00397 const Hep3Vector & u2, 00398 const Hep3Vector & u3, 00399 double u1u2, 00400 Hep3Vector & v1, // Returned vectors 00401 Hep3Vector & v2, 00402 Hep3Vector & v3 ) const; 00403 void setArbitrarily (const Hep3Vector & colX, // assumed to be of unit length 00404 Hep3Vector & v1, 00405 Hep3Vector & v2, 00406 Hep3Vector & v3) const; 00407 }; // HepRotation 00408 00409 inline 00410 std::ostream & operator << 00411 ( std::ostream & os, const HepRotation & r ) {return r.print(os);} 00412 00413 } // namespace CLHEP 00414 00415 #include "CLHEP/Vector/Rotation.icc" 00416 00417 #ifdef ENABLE_BACKWARDS_COMPATIBILITY 00418 // backwards compatibility will be enabled ONLY in CLHEP 1.9 00419 using namespace CLHEP; 00420 #endif 00421 00422 #endif /* HEP_ROTATION_H */ 00423