library: libPhysics #include "TRotation.h"

# TRotation

class description - source file - inheritance tree (.pdf)

## class TRotation : public TObject

| Inheritance Chart:
`TObject`
| <- | `TRotation` |

        protected:

                    TRotation(Double_t, Double_t, Double_t, Double_t, Double_t, Double_t, Double_t, Double_t, Double_t)

        public:

                                  TRotation()
                                  TRotation(const TRotation&)
                                  TRotation(const TQuaternion&)
                        TRotation operator*(const TRotation&) const
                        TRotation Inverse() const
                          virtual ~TRotation()
                             void AngleAxis(Double_t&, TVector3&) const
                   static TClass* Class()
                         Double_t GetXPhi() const
                         Double_t GetXPsi() const
                         Double_t GetXTheta() const
                         Double_t GetYPhi() const
                         Double_t GetYPsi() const
                         Double_t GetYTheta() const
                       TRotation& Invert()
                  virtual TClass* IsA() const
                           Bool_t IsIdentity() const
                             void MakeBasis(TVector3& xAxis, TVector3& yAxis, TVector3& zAxis) const
                           Bool_t operator!=(const TRotation& m) const
                         Double_t operator()(int, int) const
                         TVector3 operator*(const TVector3& p) const
                       TRotation& operator*=(const TRotation& m)
                       TRotation& operator=(const TRotation& m)
                           Bool_t operator==(const TRotation& m) const
          TRotation::TRotationRow operator[](int i) const
                         Double_t PhiX() const
                         Double_t PhiY() const
                         Double_t PhiZ() const
                       TRotation& Rotate(Double_t, const TVector3&)
                       TRotation& Rotate(Double_t psi, const TVector3* p)
                       TRotation& RotateAxes(const TVector3& newX, const TVector3& newY, const TVector3& newZ)
                       TRotation& RotateX(Double_t)
                       TRotation& RotateXEulerAngles(Double_t phi, Double_t theta, Double_t psi)
                       TRotation& RotateY(Double_t)
                       TRotation& RotateYEulerAngles(Double_t phi, Double_t theta, Double_t psi)
                       TRotation& RotateZ(Double_t)
                       TRotation& SetToIdentity()
                       TRotation& SetXAxis(const TVector3& axis)
                       TRotation& SetXAxis(const TVector3& axis, const TVector3& xyPlane)
                       TRotation& SetXEulerAngles(Double_t phi, Double_t theta, Double_t psi)
                             void SetXPhi(Double_t)
                             void SetXPsi(Double_t)
                             void SetXTheta(Double_t)
                       TRotation& SetYAxis(const TVector3& axis)
                       TRotation& SetYAxis(const TVector3& axis, const TVector3& yzPlane)
                       TRotation& SetYEulerAngles(Double_t phi, Double_t theta, Double_t psi)
                             void SetYPhi(Double_t)
                             void SetYPsi(Double_t)
                             void SetYTheta(Double_t)
                       TRotation& SetZAxis(const TVector3& axis)
                       TRotation& SetZAxis(const TVector3& axis, const TVector3& zxPlane)
                     virtual void ShowMembers(TMemberInspector& insp, char* parent)
                     virtual void Streamer(TBuffer& b)
                             void StreamerNVirtual(TBuffer& b)
                         Double_t ThetaX() const
                         Double_t ThetaY() const
                         Double_t ThetaZ() const
                       TRotation& Transform(const TRotation& m)
                         Double_t XX() const
                         Double_t XY() const
                         Double_t XZ() const
                         Double_t YX() const
                         Double_t YY() const
                         Double_t YZ() const
                         Double_t ZX() const
                         Double_t ZY() const
                         Double_t ZZ() const

### Data Members

        protected:

          Double_t fxx
          Double_t fxy
          Double_t fxz
          Double_t fyx
          Double_t fyy
          Double_t fyz
          Double_t fzx
          Double_t fzy
          Double_t fzz

## Class Description

    *-*-*-*-*-*-*-*-*-*-*-*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 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 o`perator *=` of the
TVector3 class:``

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

TRotation() : fxx(1.0), fxy(0.0), fxz(0.0), fyx(0.0), fyy(1.0), fyz(0.0), fzx(0.0), fzy(0.0), fzz(1.0)

TRotation(const TRotation & m) : TObject(m), fxx(m.fxx), fxy(m.fxy), fxz(m.fxz), fyx(m.fyx), fyy(m.fyy), fyz(m.fyz), fzx(m.fzx), fzy(m.fzy), fzz(m.fzz)

TRotation(Double_t mxx, Double_t mxy, Double_t mxz, Double_t myx, Double_t myy, Double_t myz, Double_t mzx, Double_t mzy, Double_t mzz) : fxx(mxx), fxy(mxy), fxz(mxz), fyx(myx), fyy(myy), fyz(myz), fzx(mzx), fzy(mzy), fzz(mzz)

TRotation(const TQuaternion & Q)

     Constructor for a rotation based on a Quaternion
     if magnitude of quaternion is null, creates identity rotation
     if quaternion is non-unit, creates rotation corresponding to the normalized (unit) quaternion

TRotation& Rotate(Double_t a, const TVector3& axis)

TRotation& RotateX(Double_t a)

TRotation& RotateY(Double_t a)

TRotation& RotateZ(Double_t a)

TRotation& RotateAxes(const TVector3 &newX, const TVector3 &newY, const TVector3 &newZ)

Double_t PhiX() const

Double_t PhiY() const

Double_t PhiZ() const

Double_t ThetaX() const

Double_t ThetaY() const

Double_t ThetaZ() const

void AngleAxis(Double_t &angle, TVector3 &axis) const

TRotation& SetXEulerAngles(Double_t phi, Double_t theta, Double_t psi)

     Rotate using the x-convention (Landau and Lifshitz, Goldstein, &c) by
     doing the explicit rotations.  This is slightly less efficient than
     directly applying the rotation, but makes the code much clearer.  My
     presumption is that this code is not going to be a speed bottle neck.

TRotation& SetYEulerAngles(Double_t phi, Double_t theta, Double_t psi)

     Rotate using the y-convention.

TRotation& RotateXEulerAngles(Double_t phi, Double_t theta, Double_t psi)

TRotation& RotateYEulerAngles(Double_t phi, Double_t theta, Double_t psi)

void SetXPhi(Double_t phi)

void SetXTheta(Double_t theta)

void SetXPsi(Double_t psi)

void SetYPhi(Double_t phi)

void SetYTheta(Double_t theta)

void SetYPsi(Double_t psi)

Double_t GetXPhi(void) const

Double_t GetYPhi(void) const

Double_t GetXTheta(void) const

Double_t GetYTheta(void) const

Double_t GetXPsi(void) const

Double_t GetYPsi(void) const

TRotation& SetXAxis(const TVector3& axis, const TVector3& xyPlane)

TRotation& SetXAxis(const TVector3& axis)

TRotation& SetYAxis(const TVector3& axis, const TVector3& yzPlane)

TRotation& SetYAxis(const TVector3& axis)

TRotation& SetZAxis(const TVector3& axis, const TVector3& zxPlane)

TRotation& SetZAxis(const TVector3& axis)

void MakeBasis(TVector3& xAxis, TVector3& yAxis, TVector3& zAxis) const

     Make the zAxis into a unit variable.

### Inline Functions

                               void ~TRotation()
                           Double_t XX() const
                           Double_t XY() const
                           Double_t XZ() const
                           Double_t YX() const
                           Double_t YY() const
                           Double_t YZ() const
                           Double_t ZX() const
                           Double_t ZY() const
                           Double_t ZZ() const
            TRotation::TRotationRow operator[](int i) const
                           Double_t operator()(int, int) const
                         TRotation& operator=(const TRotation& m)
                             Bool_t operator==(const TRotation& m) const
                             Bool_t operator!=(const TRotation& m) const
                             Bool_t IsIdentity() const
                           TVector3 operator*(const TVector3& p) const
                          TRotation operator*(const TRotation&) const
                         TRotation& operator*=(const TRotation& m)
                         TRotation& Transform(const TRotation& m)
                          TRotation Inverse() const
                         TRotation& Invert()
                         TRotation& Rotate(Double_t psi, const TVector3* p)
                         TRotation& SetToIdentity()
                            TClass* Class()
                            TClass* IsA() const
                               void ShowMembers(TMemberInspector& insp, char* parent)
                               void Streamer(TBuffer& b)
                               void StreamerNVirtual(TBuffer& b)

Author: Peter Malzacher 19/06/99
Last update: root/physics:$Name: $:$Id: TRotation.cxx,v 1.8 2005/06/28 10:16:12 brun Exp $