CLHEP VERSION Reference Documentation     CLHEP Home Page     CLHEP Documentation     CLHEP Bug Reports

Transform3D.h

Go to the documentation of this file.

// -*- C++ -*-
// $Id: Transform3D.h,v 1.5 2010/06/16 16:21:27 garren Exp $
// ---------------------------------------------------------------------------
//
// This file is a part of the CLHEP - a Class Library for High Energy Physics.
//
// Hep geometrical 3D Transformation class
//
// Author: Evgeni Chernyaev <Evgueni.Tcherniaev@cern.ch>
//
//          ******************************************
//          *                                        *
//          *               Transform                *
//          *               /  / \  \                *
//          *       --------  /   \  --------        *
//          *      /         /     \         \       *
//          *   Rotate Translate  Reflect   Scale    *
//          *    / | \    / | \    / | \    / | \    *
//          *   X  Y  Z  X  Y  Z  X  Y  Z  X  Y  Z   *
//          *                                        *
//          ******************************************
//
// Identity transformation:
//   Transform3D::Identity   - global identity transformation;
//   any constructor without parameters, e.g. Transform3D();
//   m.setIdentity()            - set "m" to identity;
//
// General transformations:
//   Transform3D(m,v)         - transformation given by Rotation "m"
//                              and CLHEP::Hep3Vector "v";
//   Transform3D(a0,a1,a2, b0,b1,b2) - transformation given by initial
//                               and transformed positions of three points;
// Rotations:
//   Rotate3D(m)              - rotation given by CLHEP::HepRotation "m";
//   Rotate3D(ang,v)          - rotation through the angle "ang" around
//                              vector "v";
//   Rotate3D(ang,p1,p2)      - rotation through the angle "ang"
//                              counterclockwise around the axis given by
//                              two points p1->p2;
//   Rotate3D(a1,a2, b1,b2)   - rotation around the origin defined by initial
//                              and transformed positions of two points;
//   RotateX3D(ang)           - rotation around X-axis;
//   RotateY3D(ang)           - rotation around Y-axis;
//   RotateZ3D(ang)           - rotation around Z-axis;
//
// Translations:
//   Translate3D(v)           - translation given by CLHEP::Hep3Vector "v";
//   Translate3D(dx,dy,dz)    - translation on vector (dx,dy,dz);
//   TraslateX3D(dx)          - translation along X-axis;
//   TraslateY3D(dy)          - translation along Y-axis;
//   TraslateZ3D(dz)          - translation along Z-axis;
//
// Reflections:
//   Reflect3D(a,b,c,d)       - reflection in the plane a*x+b*y+c*z+d=0;
//   Reflect3D(normal,p)      - reflection in the plane going through "p"
//                              and whose normal is equal to "normal";
//   ReflectX3D(a)            - reflect X in the plane x=a (default a=0);
//   ReflectY3D(a)            - reflect Y in the plane y=a (default a=0);
//   ReflectZ3D(a)            - reflect Z in the plane z=a (default a=0);
//
// Scalings:
//   Scale3D(sx,sy,sz)        - general scaling with factors "sx","sy","sz"
//                                 along X, Y and Z;
//   Scale3D(s)               - scaling with constant factor "s" along all 
//                                 directions;
//   ScaleX3D(sx)             - scale X;
//   ScaleY3D(sy)             - scale Y;
//   ScaleZ3D(sz)             - scale Z;
//
// Inverse transformation:
//   m.inverse() or           - returns inverse transformation;
//
// Compound transformation:
//   m3 = m2 * m1             - it is relatively slow in comparison with
//                              transformation of a vector. Use parenthesis
//                              to avoid this operation (see example below);
// Transformation of point:
//   p2 = m * p1
//
// Transformation of vector:
//   v2 = m * v1
//
// Transformation of normal:
//   n2 = m * n1
//
// The following table explains how different transformations affect
// point, vector and normal. "+" means affect, "-" means do not affect,
// "*" meas affect but in different way than "+" 
//
//                     Point  Vector  Normal
//      -------------+-------+-------+-------
//       Rotation    !   +   !   +   !   +
//       Translation !   +   !   -   !   -
//       Reflection  !   +   !   +   !   *
//       Scaling     !   +   !   +   !   *
//      -------------+-------+-------+-------
//
// Example of the usage:
//
//   Transform3D m1, m2, m3;
//   HepVector3D    v2, v1(0,0,0);
//
//   m1 = Rotate3D(angle, Vector3D(1,1,1));
//   m2 = Translate3D(dx,dy,dz);
//   m3 = m1.inverse();
//
//   v2 = m3*(m2*(m1*v1));
//
// History:
// 24.09.96 E.Chernyaev - initial version
//
// 26.02.97 E.Chernyaev
// - added global Identity by request of John Allison 
//   (to avoid problems with compilation on HP) 
// - added getRotation and getTranslation 
//
// 29.01.01 E.Chernyaev - added subscripting
// 11.06.01 E.Chernyaev - added getDecomposition

#ifndef HEP_TRANSFROM3D_H
#define HEP_TRANSFROM3D_H

#include "CLHEP/Geometry/defs.h"
#include "CLHEP/Vector/ThreeVector.h"

namespace HepGeom {

  template<class T> class Point3D;
  template<class T> class Vector3D;
  template<class T> class Normal3D;

  class Translate3D;
  class Rotate3D;
  class Scale3D;

  class Transform3D {
  protected:
    double xx_, xy_, xz_, dx_,     // 4x3  Transformation Matrix
           yx_, yy_, yz_, dy_,
           zx_, zy_, zz_, dz_;

    // Protected constructor
    Transform3D(double XX, double XY, double XZ, double DX,
                double YX, double YY, double YZ, double DY,
                double ZX, double ZY, double ZZ, double DZ)
      : xx_(XX), xy_(XY), xz_(XZ), dx_(DX),
        yx_(YX), yy_(YY), yz_(YZ), dy_(DY),
        zx_(ZX), zy_(ZY), zz_(ZZ), dz_(DZ) {}

    // Set transformation matrix
    void setTransform(double XX, double XY, double XZ, double DX,
                      double YX, double YY, double YZ, double DY,
                      double ZX, double ZY, double ZZ, double DZ) {
      xx_ = XX; xy_ = XY; xz_ = XZ; dx_ = DX;
      yx_ = YX; yy_ = YY; yz_ = YZ; dy_ = DY;
      zx_ = ZX; zy_ = ZY; zz_ = ZZ; dz_ = DZ;
    }

  public:
    static const Transform3D Identity;

    // Helper class for implemention of C-style subscripting r[i][j] 
    class Transform3D_row {
    public:
      inline Transform3D_row(const Transform3D &, int);
      inline double operator [] (int) const;
    private:
      const Transform3D & rr;
      int ii;
    };

    Transform3D()
      : xx_(1), xy_(0), xz_(0), dx_(0),
        yx_(0), yy_(1), yz_(0), dy_(0),
        zx_(0), zy_(0), zz_(1), dz_(0) {}
  
    inline Transform3D(const CLHEP::HepRotation & m, const CLHEP::Hep3Vector & v);

    Transform3D(const Point3D<double> & fr0,
                const Point3D<double> & fr1,
                const Point3D<double> & fr2,
                const Point3D<double> & to0,
                const Point3D<double> & to1,
                const Point3D<double> & to2);

    Transform3D(const Transform3D & m)
      : xx_(m.xx_), xy_(m.xy_), xz_(m.xz_), dx_(m.dx_),
        yx_(m.yx_), yy_(m.yy_), yz_(m.yz_), dy_(m.dy_),
        zx_(m.zx_), zy_(m.zy_), zz_(m.zz_), dz_(m.dz_) {}

    ~Transform3D() { /* nop */ }

    inline const Transform3D_row operator [] (int) const; 

    double operator () (int, int) const;

    double xx() const { return xx_; }
    double xy() const { return xy_; }
    double xz() const { return xz_; }
    double yx() const { return yx_; }
    double yy() const { return yy_; }
    double yz() const { return yz_; }
    double zx() const { return zx_; }
    double zy() const { return zy_; }
    double zz() const { return zz_; }
    double dx() const { return dx_; }
    double dy() const { return dy_; }
    double dz() const { return dz_; }
    
    Transform3D & operator=(const Transform3D &m) {
      xx_= m.xx_; xy_= m.xy_; xz_= m.xz_; dx_= m.dx_;
      yx_= m.yx_; yy_= m.yy_; yz_= m.yz_; dy_= m.dy_;
      zx_= m.zx_; zy_= m.zy_; zz_= m.zz_; dz_= m.dz_;
      return *this;
    }

    void setIdentity() { 
      xy_= xz_= dx_= yx_= yz_= dy_= zx_= zy_= dz_= 0; xx_= yy_= zz_= 1;
    }
    
    Transform3D inverse() const;
    
    Transform3D operator*(const Transform3D & b) const;
    
    void getDecomposition(Scale3D & scale,
                          Rotate3D & rotation,
                          Translate3D & translation) const;

    bool isNear(const Transform3D & t, double tolerance = 2.2E-14 ) const;

    inline CLHEP::HepRotation getRotation() const;
    
    inline CLHEP::Hep3Vector getTranslation() const;
    
    bool operator == (const Transform3D & transform) const;
    
    bool operator != (const Transform3D & transform) const {
      return ! operator==(transform);
    }
  };

  //   R O T A T I O N S

  class Rotate3D : public Transform3D {
  public:
    Rotate3D() : Transform3D() {}
    
    inline Rotate3D(const CLHEP::HepRotation &m);

    Rotate3D(double a,
             const Point3D<double> & p1,
             const Point3D<double> & p2);
    
    inline Rotate3D(double a, const Vector3D<double> & v);

    inline Rotate3D(const Point3D<double> & fr1,
                    const Point3D<double> & fr2,
                    const Point3D<double> & to1,
                    const Point3D<double> & to2);
  };

  class RotateX3D : public Rotate3D {
  public:
    RotateX3D() : Rotate3D() {}
    
    RotateX3D(double a) {
      double cosa = std::cos(a), sina = std::sin(a); 
      setTransform(1,0,0,0,  0,cosa,-sina,0,  0,sina,cosa,0);
    }
  };

  class RotateY3D : public Rotate3D {
  public:
    RotateY3D() : Rotate3D() {}
    
    RotateY3D(double a) {
      double cosa = std::cos(a), sina = std::sin(a); 
      setTransform(cosa,0,sina,0,  0,1,0,0,  -sina,0,cosa,0);
    }
  };

  class RotateZ3D : public Rotate3D {
  public:
    RotateZ3D() : Rotate3D() {}
    
    RotateZ3D(double a) {
      double cosa = std::cos(a), sina = std::sin(a); 
      setTransform(cosa,-sina,0,0,  sina,cosa,0,0,  0,0,1,0);
    }
  };

  //   T R A N S L A T I O N S
  
  class Translate3D : public Transform3D {
  public:
    Translate3D() : Transform3D() {}
    
    inline Translate3D(const CLHEP::Hep3Vector &v);
    
    Translate3D(double x, double y, double z)
      : Transform3D(1,0,0,x, 0,1,0,y, 0,0,1,z) {}
  };

  class TranslateX3D : public Translate3D {
  public:
    TranslateX3D() : Translate3D() {}
    
    TranslateX3D(double x) : Translate3D(x, 0, 0) {}
  };

  class TranslateY3D : public Translate3D {
  public:
    TranslateY3D() : Translate3D() {}

    TranslateY3D(double y) : Translate3D(0, y, 0) {}
  };

  class TranslateZ3D : public Translate3D {
  public:
    TranslateZ3D() : Translate3D() {}

    TranslateZ3D(double z) : Translate3D(0, 0, z) {}
  };

  //   R E F L E C T I O N S

  class Reflect3D : public Transform3D {
  protected:
    Reflect3D(double XX, double XY, double XZ, double DX,
                 double YX, double YY, double YZ, double DY,
                 double ZX, double ZY, double ZZ, double DZ)
      : Transform3D(XX,XY,XZ,DX, YX,YY,YZ,DY, ZX,ZY,ZZ,DZ) {}

  public:
    Reflect3D() : Transform3D() {}

    Reflect3D(double a, double b, double c, double d);

    inline Reflect3D(const Normal3D<double> & normal,
                        const Point3D<double> & point);
  };

  class ReflectX3D : public Reflect3D {
  public:
    ReflectX3D(double x=0) : Reflect3D(-1,0,0,x+x, 0,1,0,0, 0,0,1,0) {}
  };
 
  class ReflectY3D : public Reflect3D {
  public:
    ReflectY3D(double y=0) : Reflect3D(1,0,0,0, 0,-1,0,y+y, 0,0,1,0) {}
  };
 
  class ReflectZ3D : public Reflect3D {
  public:
    ReflectZ3D(double z=0) : Reflect3D(1,0,0,0, 0,1,0,0, 0,0,-1,z+z) {}
  };
 
  //   S C A L I N G S

  class Scale3D : public Transform3D {
  public:
    Scale3D() : Transform3D() {}

    Scale3D(double x, double y, double z)
      : Transform3D(x,0,0,0, 0,y,0,0, 0,0,z,0) {}

    Scale3D(double s)
      : Transform3D(s,0,0,0, 0,s,0,0, 0,0,s,0) {}
  };

  class ScaleX3D : public Scale3D {
  public:
    ScaleX3D() : Scale3D() {}

    ScaleX3D(double x) : Scale3D(x, 1, 1) {}
  };

  class ScaleY3D : public Scale3D {
  public:
    ScaleY3D() : Scale3D() {}

    ScaleY3D(double y) : Scale3D(1, y, 1) {}
  };

  class ScaleZ3D : public Scale3D {
  public:
    ScaleZ3D() : Scale3D() {}
    ScaleZ3D(double z) : Scale3D(1, 1, z) {}
  };
} /* namespace HepGeom */

#ifdef ENABLE_BACKWARDS_COMPATIBILITY
//  backwards compatibility will be enabled ONLY in CLHEP 1.9
typedef HepGeom::Transform3D  HepTransform3D; 
typedef HepGeom::Rotate3D     HepRotate3D;
typedef HepGeom::RotateX3D    HepRotateX3D;
typedef HepGeom::RotateY3D    HepRotateY3D;
typedef HepGeom::RotateZ3D    HepRotateZ3D;
typedef HepGeom::Translate3D  HepTranslate3D;
typedef HepGeom::TranslateX3D HepTranslateX3D;
typedef HepGeom::TranslateY3D HepTranslateY3D;
typedef HepGeom::TranslateZ3D HepTranslateZ3D;
typedef HepGeom::Reflect3D    HepReflect3D; 
typedef HepGeom::ReflectX3D   HepReflectX3D;
typedef HepGeom::ReflectY3D   HepReflectY3D;
typedef HepGeom::ReflectZ3D   HepReflectZ3D;
typedef HepGeom::Scale3D      HepScale3D;
typedef HepGeom::ScaleX3D     HepScaleX3D;
typedef HepGeom::ScaleY3D     HepScaleY3D;
typedef HepGeom::ScaleZ3D     HepScaleZ3D;
#endif

#include "CLHEP/Geometry/Transform3D.icc"

#endif /* HEP_TRANSFROM3D_H */

---