CLHEP/Vector/Rotation.h

0001 // -*- C++ -*-
0002 // CLASSDOC OFF
0003 // $Id: Rotation.h,v 1.3 2003/10/23 21:29:52 garren Exp $
0004 // ---------------------------------------------------------------------------
0005 // CLASSDOC ON
0006 //
0007 // This file is a part of the CLHEP - a Class Library for High Energy Physics.
0008 //
0009 // This is the definition of the HepRotation class for performing rotations
0010 // on objects of the Hep3Vector (and HepLorentzVector) class.
0011 //
0012 // HepRotation is a concrete implementation of Hep3RotationInterface.
0013 //
0014 // .SS See Also
0015 // RotationInterfaces.h
0016 // ThreeVector.h, LorentzVector.h, LorentzRotation.h
0017 //
0018 // .SS Author
0019 // Leif Lonnblad, Mark Fischler
0020
0021 #ifndef HEP_ROTATION_H
0022 #define HEP_ROTATION_H
0023
0024 #include "CLHEP/Vector/defs.h"
0025 #include "CLHEP/Vector/RotationInterfaces.h"
0026 #include "CLHEP/Vector/RotationX.h"
0027 #include "CLHEP/Vector/RotationY.h"
0028 #include "CLHEP/Vector/RotationZ.h"
0029 #include "CLHEP/Vector/LorentzVector.h"
0030
0031 namespace CLHEP {
0032
0033 // Declarations of classes and global methods
0034 class HepRotation;
0035 inline HepRotation inverseOf ( const HepRotation & r );
0036 inline HepRotation operator * (const HepRotationX & rx, const HepRotation & r);
0037 inline HepRotation operator * (const HepRotationY & ry, const HepRotation & r);
0038 inline HepRotation operator * (const HepRotationZ & rz, const HepRotation & r);
0039
0040 /**
0041  * @author
0042  * @ingroup vector
0043  */
0044 class HepRotation {
0045
0046 public:
0047
0048   // ----------  Constructors and Assignment:
0049
0050   inline HepRotation();
0051   // Default constructor. Gives a unit matrix.
0052
0053   inline HepRotation(const HepRotation & m);
0054   inline HepRotation(HepRotation && m) = default;
0055   // Copy and move constructors.
0056
0057   inline HepRotation(const HepRotationX & m);
0058   inline HepRotation(const HepRotationY & m);
0059   inline HepRotation(const HepRotationZ & m);
0060   // Construct from specialized rotation.
0061
0062   HepRotation & set( const Hep3Vector & axis, double delta );
0063   HepRotation      ( const Hep3Vector & axis, double delta );
0064   // Construct from axis and angle.
0065
0066   HepRotation & set( const HepAxisAngle & ax );
0067   HepRotation      ( const HepAxisAngle & ax );
0068   // Construct from AxisAngle structure.
0069
0070   HepRotation & set( double phi, double theta, double psi );
0071   HepRotation      ( double phi, double theta, double psi );
0072   // Construct from three Euler angles (in radians).
0073
0074   HepRotation & set( const HepEulerAngles & e );
0075   HepRotation      ( const HepEulerAngles & e );
0076   // Construct from EulerAngles structure.
0077
0078   HepRotation ( const Hep3Vector & colX,
0079                 const Hep3Vector & colY,
0080                 const Hep3Vector & colZ );
0081   // Construct from three *orthogonal* unit vector columns.
0082     // NOTE:
0083     //       This constructor, and the two set methods below,
0084     //   will check that the columns (or rows) form an orthonormal
0085     //   matrix, and will adjust values so that this relation is
0086     //   as exact as possible.
0087
0088   HepRotation & set( const Hep3Vector & colX,
0089                              const Hep3Vector & colY,
0090                              const Hep3Vector & colZ );
0091   //   supply three *orthogonal* unit vectors for the columns.
0092
0093   HepRotation & setRows( const Hep3Vector & rowX,
0094                                  const Hep3Vector & rowY,
0095                                  const Hep3Vector & rowZ );
0096   //   supply three *orthogonal* unit vectors for the rows.
0097
0098   inline HepRotation & set(const HepRotationX & r);
0099   inline HepRotation & set(const HepRotationY & r);
0100   inline HepRotation & set(const HepRotationZ & r);
0101   // set from specialized rotation.
0102
0103   inline  HepRotation & operator = (const HepRotation & r);
0104   inline  HepRotation & operator = (HepRotation && r) = default;
0105   // Copy and move assignment operators.
0106
0107   inline  HepRotation & operator = (const HepRotationX & r);
0108   inline  HepRotation & operator = (const HepRotationY & r);
0109   inline  HepRotation & operator = (const HepRotationZ & r);
0110   // Assignment from specialized rotation.
0111
0112   inline HepRotation &set( const HepRep3x3 & m );
0113   inline HepRotation     ( const HepRep3x3 & m );
0114   // WARNING - NO CHECKING IS DONE!
0115   // Constructon directly from from a 3x3 representation,
0116   // which is required to be an orthogonal matrix.
0117
0118   inline ~HepRotation();
0119   // Trivial destructor.
0120
0121   // ----------  Accessors:
0122
0123   inline Hep3Vector colX() const;
0124   inline Hep3Vector colY() const;
0125   inline Hep3Vector colZ() const;
0126   // orthogonal unit-length column vectors
0127
0128   inline Hep3Vector rowX() const;
0129   inline Hep3Vector rowY() const;
0130   inline Hep3Vector rowZ() const;
0131   // orthogonal unit-length row vectors
0132
0133   inline double xx() const;
0134   inline double xy() const;
0135   inline double xz() const;
0136   inline double yx() const;
0137   inline double yy() const;
0138   inline double yz() const;
0139   inline double zx() const;
0140   inline double zy() const;
0141   inline double zz() const;
0142   // Elements of the rotation matrix (Geant4).
0143
0144   inline HepRep3x3 rep3x3() const;
0145   //   3x3 representation:
0146
0147   // ------------  Subscripting:
0148
0149   class HepRotation_row {
0150   public:
0151     inline HepRotation_row(const HepRotation &, int);
0152     inline double operator [] (int) const;
0153   private:
0154     const HepRotation & rr;
0155     int ii;
0156   };
0157   // Helper class for implemention of C-style subscripting r[i][j]
0158
0159   inline const HepRotation_row operator [] (int) const;
0160   // Returns object of the helper class for C-style subscripting r[i][j]
0161   // i and j range from 0 to 2.
0162
0163   double operator () (int, int) const;
0164   // Fortran-style subscripting: returns (i,j) element of the rotation matrix.
0165   // Note:  i and j still range from 0 to 2.            [Rotation.cc]
0166
0167   // ------------  Euler angles:
0168   inline  double getPhi  () const;
0169   inline  double getTheta() const;
0170   inline  double getPsi  () const;
0171   double    phi  () const;
0172   double    theta() const;
0173   double    psi  () const;
0174   HepEulerAngles eulerAngles() const;
0175
0176   // ------------  axis & angle of rotation:
0177   inline  double  getDelta() const;
0178   inline  Hep3Vector getAxis () const;
0179   double     delta() const;
0180   Hep3Vector    axis () const;
0181   HepAxisAngle  axisAngle() const;
0182   void getAngleAxis(double & delta, Hep3Vector & axis) const;
0183   // Returns the rotation angle and rotation axis (Geant4).     [Rotation.cc]
0184
0185   // ------------- Angles of rotated axes
0186   double phiX() const;
0187   double phiY() const;
0188   double phiZ() const;
0189   double thetaX() const;
0190   double thetaY() const;
0191   double thetaZ() const;
0192   // Return angles (RADS) made by rotated axes against original axes (Geant4).
0193   //                                [Rotation.cc]
0194
0195   // ----------  Other accessors treating pure rotation as a 4-rotation
0196
0197   inline HepLorentzVector col1() const;
0198   inline HepLorentzVector col2() const;
0199   inline HepLorentzVector col3() const;
0200   //  orthosymplectic 4-vector columns - T component will be zero
0201
0202   inline HepLorentzVector col4() const;
0203   // Will be (0,0,0,1) for this pure Rotation.
0204
0205   inline HepLorentzVector row1() const;
0206   inline HepLorentzVector row2() const;
0207   inline HepLorentzVector row3() const;
0208   //  orthosymplectic 4-vector rows - T component will be zero
0209
0210   inline HepLorentzVector row4() const;
0211   // Will be (0,0,0,1) for this pure Rotation.
0212
0213   inline double xt() const;
0214   inline double yt() const;
0215   inline double zt() const;
0216   inline double tx() const;
0217   inline double ty() const;
0218   inline double tz() const;
0219   // Will be zero for this pure Rotation
0220
0221   inline double tt() const;
0222   // Will be one for this pure Rotation
0223
0224   inline HepRep4x4 rep4x4() const;
0225   //   4x4 representation.
0226
0227   // ---------   Mutators
0228
0229   void setPhi (double phi);
0230   // change Euler angle phi, leaving theta and psi unchanged.
0231
0232   void setTheta (double theta);
0233   // change Euler angle theta, leaving phi and psi unchanged.
0234
0235   void setPsi (double psi);
0236   // change Euler angle psi, leaving theta and phi unchanged.
0237
0238   void setAxis (const Hep3Vector & axis);
0239   // change rotation axis, leaving delta unchanged.
0240
0241   void setDelta (double delta);
0242   // change angle of rotation, leaving rotation axis unchanged.
0243
0244   // ----------  Decomposition:
0245
0246   void decompose (HepAxisAngle & rotation, Hep3Vector & boost) const;
0247   void decompose (Hep3Vector & boost, HepAxisAngle & rotation) const;
0248   // These are trivial, as the boost vector is 0.       [RotationP.cc]
0249
0250   // ----------  Comparisons:
0251
0252   bool isIdentity() const;
0253   // Returns true if the identity matrix (Geant4).      [Rotation.cc]
0254
0255   int compare( const HepRotation & r  ) const;
0256   // Dictionary-order comparison, in order zz, zy, zx, yz, ... xx
0257   // Used in operator<, >, <=, >=
0258
0259   inline bool operator== ( const HepRotation & r ) const;
0260   inline bool operator!= ( const HepRotation & r ) const;
0261   inline bool operator<  ( const HepRotation & r ) const;
0262   inline bool operator>  ( const HepRotation & r ) const;
0263   inline bool operator<= ( const HepRotation & r ) const;
0264   inline bool operator>= ( const HepRotation & r ) const;
0265
0266   double distance2( const HepRotation &  r  ) const;
0267   // 3 - Tr ( this/r ) -- This works with RotationX, Y or Z also
0268
0269   double howNear( const HepRotation & r ) const;
0270   bool isNear( const HepRotation & r,
0271              double epsilon=Hep4RotationInterface::tolerance) const;
0272
0273   double distance2( const HepBoost           & lt  ) const;
0274   // 3 - Tr ( this ) + |b|^2 / (1-|b|^2)
0275   double distance2( const HepLorentzRotation & lt  ) const;
0276   // 3 - Tr ( this/r ) + |b|^2 / (1-|b|^2) where b is the boost vector of lt
0277
0278   double howNear( const HepBoost           & lt ) const;
0279   double howNear( const HepLorentzRotation & lt ) const;
0280   bool isNear( const HepBoost           & lt,
0281              double epsilon=Hep4RotationInterface::tolerance) const;
0282   bool isNear( const HepLorentzRotation & lt,
0283              double epsilon=Hep4RotationInterface::tolerance) const;
0284
0285   // ----------  Properties:
0286
0287   double norm2() const;
0288   // distance2 (IDENTITY), which is 3 - Tr ( *this )
0289
0290   void rectify();
0291   // non-const but logically moot correction for accumulated roundoff errors
0292     // rectify averages the matrix with the transpose of its actual
0293     // inverse (absent accumulated roundoff errors, the transpose IS
0294     // the inverse)); this removes to first order those errors.
0295     // Then it formally extracts axis and delta, and forms a true
0296     // HepRotation with those values of axis and delta.
0297
0298   // ---------- Application:
0299
0300   inline Hep3Vector operator() (const Hep3Vector & p) const;
0301   // Rotate a Hep3Vector.
0302
0303   inline  Hep3Vector operator * (const Hep3Vector & p) const;
0304   // Multiplication with a Hep3Vector.
0305
0306   inline HepLorentzVector operator()( const HepLorentzVector & w ) const;
0307   // Rotate (the space part of) a HepLorentzVector.
0308
0309   inline  HepLorentzVector operator* ( const HepLorentzVector & w ) const;
0310   // Multiplication with a HepLorentzVector.
0311
0312   // ---------- Operations in the group of Rotations
0313
0314   inline HepRotation operator * (const HepRotation & r) const;
0315   // Product of two rotations (this) * r - matrix multiplication
0316
0317   inline HepRotation operator * (const HepRotationX & rx) const;
0318   inline HepRotation operator * (const HepRotationY & ry) const;
0319   inline HepRotation operator * (const HepRotationZ & rz) const;
0320   // Product of two rotations (this) * r - faster when specialized type
0321
0322   inline  HepRotation & operator *= (const HepRotation & r);
0323   inline  HepRotation & transform   (const HepRotation & r);
0324   // Matrix multiplication.
0325   // Note a *= b; <=> a = a * b; while a.transform(b); <=> a = b * a;
0326
0327   inline  HepRotation & operator *= (const HepRotationX & r);
0328   inline  HepRotation & operator *= (const HepRotationY & r);
0329   inline  HepRotation & operator *= (const HepRotationZ & r);
0330   inline  HepRotation & transform   (const HepRotationX & r);
0331   inline  HepRotation & transform   (const HepRotationY & r);
0332   inline  HepRotation & transform   (const HepRotationZ & r);
0333   // Matrix multiplication by specialized matrices
0334
0335   HepRotation & rotateX(double delta);
0336   // Rotation around the x-axis; equivalent to R = RotationX(delta) * R
0337
0338   HepRotation & rotateY(double delta);
0339   // Rotation around the y-axis; equivalent to R = RotationY(delta) * R
0340
0341   HepRotation & rotateZ(double delta);
0342   // Rotation around the z-axis; equivalent to R = RotationZ(delta) * R
0343
0344          HepRotation & rotate(double delta, const Hep3Vector & axis);
0345   inline HepRotation & rotate(double delta, const Hep3Vector * axis);
0346   // Rotation around a specified vector.
0347   // r.rotate(d,a) is equivalent to r = Rotation(d,a) * r
0348
0349   HepRotation & rotateAxes(const Hep3Vector & newX,
0350                            const Hep3Vector & newY,
0351                            const Hep3Vector & newZ);
0352   // Rotation of local axes defined by 3 orthonormal vectors (Geant4).
0353   // Equivalent to r = Rotation (newX, newY, newZ) * r
0354
0355   inline HepRotation inverse() const;
0356   // Returns the inverse.
0357
0358   inline HepRotation & invert();
0359   // Inverts the Rotation matrix.
0360
0361   // ---------- I/O:
0362
0363   std::ostream & print( std::ostream & os ) const;
0364   // Aligned six-digit-accurate output of the  rotation matrix. [RotationIO.cc]
0365
0366   // ---------- Identity Rotation:
0367
0368   static const HepRotation IDENTITY;
0369
0370   // ---------- Tolerance
0371
0372   static inline double getTolerance();
0373   static inline double setTolerance(double tol);
0374
0375 protected:
0376
0377   inline HepRotation(double mxx, double mxy, double mxz,
0378              double myx, double myy, double myz,
0379              double mzx, double mzy, double mzz);
0380   // Protected constructor.
0381   // DOES NOT CHECK FOR VALIDITY AS A ROTATION.
0382
0383   friend HepRotation operator* (const HepRotationX & rx, const HepRotation & r);
0384   friend HepRotation operator* (const HepRotationY & ry, const HepRotation & r);
0385   friend HepRotation operator* (const HepRotationZ & rz, const HepRotation & r);
0386
0387   double rxx, rxy, rxz,
0388         ryx, ryy, ryz,
0389         rzx, rzy, rzz;
0390   // The matrix elements.
0391
0392 private:
0393   bool
0394        setCols ( const Hep3Vector & u1, // Vectors assume to be of unit length
0395                  const Hep3Vector & u2,
0396                  const Hep3Vector & u3,
0397                  double u1u2,
0398                  Hep3Vector & v1,       // Returned vectors
0399                  Hep3Vector & v2,
0400                  Hep3Vector & v3 ) const;
0401   void setArbitrarily (const Hep3Vector & colX, // assumed to be of unit length
0402                       Hep3Vector & v1,
0403                       Hep3Vector & v2,
0404                       Hep3Vector & v3) const;
0405 };  // HepRotation
0406
0407 inline
0408 std::ostream & operator <<
0409     ( std::ostream & os, const HepRotation & r ) {return r.print(os);}
0410
0411 }  // namespace CLHEP
0412
0413 #include "CLHEP/Vector/Rotation.icc"
0414
0415 #ifdef ENABLE_BACKWARDS_COMPATIBILITY
0416 //  backwards compatibility will be enabled ONLY in CLHEP 1.9
0417 using namespace CLHEP;
0418 #endif
0419
0420 #endif /* HEP_ROTATION_H */
0421