$Id: rotation-howto.txt,v 1.1 2005/03/09 14:34:35 xkrivanj Exp $
Author: Jaroslav Krivanek
Date:   March 9th, 2005

-----------------------------------------------

SH rotation with LIBSPHAR
=========================

1) unzip libsphar.zip
2) compile a lib with the sources in libsphar/src
3) in your project
     - set your include directory to libsphar/include
     - link with libsphar.lib
4) put #include "shrot.h" in the source where you want to rotate

There are two different rotation algorithms:
a) Kautz's ZXZXZ decomposition (really fast, but possibly problems with
the decomposition at the poles)
b) Ivanic's recursive sh rotation matrix construction

The source is documented in doxygen format. I recommend
to refer to the source code documentation for more details.


a) Rotation with Kautz's ZXZXZ decomposition
--------------------------------------------

1)
Declare
  CZXZXZRotationObject zxzxzRotObject(maxOrder);
somewhere in your class or as a global variable.
maxOrder is the maximum SH order of the functions
you will be rotating.

Call
  rotGenerator.LiftOrder(maxOrder);
once before the forst rotation.
(rotGenerator is declared in sphar library)


2)
For a given rotation, call
  zxzxzRotObject.ToGlobalFrame(U,V,N,order);
where U,V,N is the local frame at a point that will
be aligned with the local frame (rows of the
3D rotation matrix for the desired rotation).
order is the actual order for the rotation (should be
less or equal to the maxOrder passed to the constructor).

Apply the rotation (as many times as you want):
  zxzxzRotObject.TransformVector(destvec,srcvec,order,rotGenerator);
'order' should be less or (more often) equal to the 'order' passed
to the last ToGlobalFrame() call.
float * srcvec  SH coefficients before the rotation
float * destvec SH coeffs after the rotation

b) Ratation with Ivanic's recursive matrix construction
=======================================================

1)
Call
  rotGenerator.LiftOrder(maxOrder);
once before the first rotation.

2)
For a given rotation, call
  CSHRotMatrix  shRotMatrix(order);
  rotGenerator.ToGlobalFrame(shRotMatrix,order,U,V,N);
This fills shRotMatrix.

Apply the rotation (as many times as you want)
  shRotMatrix.TransformVector(destvect,srcvect,order);

EFFICIENCY NOTE!!!
Since the constructor of CSHRotMatrix allocates memory, it is
a good idea to have one instance of CSHRotMatrix somewhere
in your class and reuse it for all rotations.

Refer to the code documentation for details.