class TRotation: public TObject

The Physics Vector package 
-*                    ==========================                       
-* The Physics Vector package consists of five classes:                
-*   - TVector2                                                        
-*   - TVector3                                                        
-*   - TRotation                                                       
-*   - TLorentzVector                                                  
-*   - TLorentzRotation                                                
-* It is a combination of CLHEPs Vector package written by             
-* Leif Lonnblad, Andreas Nilsson and Evgueni Tcherniaev               
-* and a ROOT package written by Pasha Murat.                          
-* for CLHEP see:  http://wwwinfo.cern.ch/asd/lhc++/clhep/             
*

TRotation

The TRotation class describes a rotation of objects of the TVector3 class. It is a 3*3 matrix of Double_t:

| xx  xy  xz |
| yx  yy  yz |
| zx  zy  zz |

It describes a so called active rotation, i.e. rotation of objects inside a static system of coordinates. In case you want to rotate the frame and want to know the coordinates of objects in the rotated system, you should apply the inverse rotation to the objects. If you want to transform coordinates from the rotated frame to the original frame you have to apply the direct transformation.

A rotation around a specified axis means counterclockwise rotation around the positive direction of the axis.
 

Declaration, Access, Comparisons

  TRotation r;    // r initialized as identity
  TRotation m(r); // m = r

There is no direct way to set the matrix elements - to ensure that a TRotation object always describes a real rotation. But you can get the values by the member functions XX()..ZZ() or the (,) operator:

  Double_t xx = r.XX();     //  the same as xx=r(0,0)
           xx = r(0,0);

  if (r==m) {...}          // test for equality
  if (r!=m) {..}           // test for inequality
  if (r.IsIdentity()) {...} // test for identity
 

Rotation around axes

The following matrices desrcibe counterclockwise rotations around coordinate axes

        | 1   0       0    |
Rx(a) = | 0 cos(a) -sin(a) |
        | 0 sin(a) cos(a)  |

        | cos(a)  0 sin(a) |
Ry(a) = |   0     1    0   |
        | -sin(a) 0 cos(a) |

        | cos(a) -sin(a) 0 |
Rz(a) = | sin(a) cos(a) 0 |
        |   0      0     1 |
and are implemented as member functions RotateX(), RotateY() and RotateZ():

  r.RotateX(TMath::Pi()); // rotation around the x-axis

Rotation around arbitary axis

The member function Rotate() allows to rotate around an arbitary vector (not neccessary a unit one) and returns the result.

  r.Rotate(TMath::Pi()/3,TVector3(3,4,5));

It is possible to find a unit vector and an angle, which describe the same rotation as the current one:

  Double_t angle;
  TVector3 axis;
  r.GetAngleAxis(angle,axis);

Rotation of local axes

Member function RotateAxes() adds a rotation of local axes to the current rotation and returns the result:

  TVector3 newX(0,1,0);
  TVector3 newY(0,0,1);
  TVector3 newZ(1,0,0);
  a.RotateAxes(newX,newY,newZ);

Member functions ThetaX(), ThetaY(), ThetaZ(), PhiX(), PhiY(),PhiZ() return azimuth and polar angles of the rotated axes:

  Double_t tx,ty,tz,px,py,pz;
  tx= a.ThetaX();
  ...
  pz= a.PhiZ();

Setting The Rotations

The member function SetToIdentity() will set the rotation object to the identity (no rotation). With a minor caveat, the Euler angles of the rotation may be set using SetXEulerAngles() or individually set with SetXPhi(), SetXTheta(), and SetXPsi(). These routines set the Euler angles using the X-convention which is defined by a rotation about the Z-axis, about the new X-axis, and about the new Z-axis. This is the convention used in Landau and Lifshitz, Goldstein and other common physics texts. The Y-convention euler angles can be set with SetYEulerAngles(), SetYPhi(), SetYTheta(), and SetYPsi(). The caveat is that Euler angles usually define the rotation of the new coordinate system with respect to the original system, however, the TRotation class specifies the rotation of the object in the original system (an active rotation). To recover the usual Euler rotations (ie. rotate the system not the object), you must take the inverse of the rotation. The member functions SetXAxis(), SetYAxis(), and SetZAxis() will create a rotation which rotates the requested axis of the object to be parallel to a vector. If used with one argument, the rotation about that axis is arbitrary. If used with two arguments, the second variable defines the XY, YZ, or ZX respectively.

Inverse rotation

  TRotation a,b;
  ...
  b = a.Inverse();  // b is inverse of a, a is unchanged
  b = a.Invert();   // invert a and set b = a

Compound Rotations

The operator * has been implemented in a way that follows the mathematical notation of a product of the two matrices which describe the two consecutive rotations. Therefore the second rotation should be placed first:

  r = r2 * r1;

Rotation of TVector3

The TRotation class provides an operator * which allows to express a rotation of a TVector3 analog to the mathematical notation

  | x' |   | xx xy xz | | x |
  | y' | = | yx yy yz | | y |
  | z' |   | zx zy zz | | z |

e.g.:

  TVector3 v(1,1,1);
  v = r * v;

You can also use the Transform() member function or the operator *= of the
TVector3 class:

  TVector3 v;
  TRotation r;
  v.Transform(r);
  v *= r;  //Attention v = r * v