OpenWalnut  1.2.5
 All Classes Namespaces Functions Variables Typedefs Enumerations Enumerator Friends
WSymmetricSphericalHarmonic.h
00001 //---------------------------------------------------------------------------
00002 //
00003 // Project: OpenWalnut ( http://www.openwalnut.org )
00004 //
00005 // Copyright 2009 OpenWalnut Community, BSV@Uni-Leipzig and CNCF@MPI-CBS
00006 // For more information see http://www.openwalnut.org/copying
00007 //
00008 // This file is part of OpenWalnut.
00009 //
00010 // OpenWalnut is free software: you can redistribute it and/or modify
00011 // it under the terms of the GNU Lesser General Public License as published by
00012 // the Free Software Foundation, either version 3 of the License, or
00013 // (at your option) any later version.
00014 //
00015 // OpenWalnut is distributed in the hope that it will be useful,
00016 // but WITHOUT ANY WARRANTY; without even the implied warranty of
00017 // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
00018 // GNU Lesser General Public License for more details.
00019 //
00020 // You should have received a copy of the GNU Lesser General Public License
00021 // along with OpenWalnut. If not, see <http://www.gnu.org/licenses/>.
00022 //
00023 //---------------------------------------------------------------------------
00024 
00025 #ifndef WSYMMETRICSPHERICALHARMONIC_H
00026 #define WSYMMETRICSPHERICALHARMONIC_H
00027 
00028 #include <vector>
00029 
00030 #include "../WExportCommon.h"
00031 #include "linearAlgebra/WLinearAlgebra.h"
00032 #include "WMath.h"
00033 #include "WUnitSphereCoordinates.h"
00034 #include "WMatrix.h"
00035 #include "WValue.h"
00036 
00037 /**
00038  * Class for symmetric spherical harmonics
00039  * The index scheme of the coefficients/basis values is like in the Descoteaux paper "Regularized, Fast, and Robust Analytical Q-Ball Imaging".
00040  */
00041 class OWCOMMON_EXPORT WSymmetricSphericalHarmonic  // NOLINT
00042 {
00043 // friend class WSymmetricSphericalHarmonicTest;
00044 public:
00045     /**
00046      * Default constructor.
00047      */
00048     WSymmetricSphericalHarmonic();
00049 
00050     /**
00051      * Constructor.
00052      * \param SHCoefficients the initial coefficients (stored like in the mentioned Descoteaux paper).
00053      */
00054     explicit WSymmetricSphericalHarmonic( const WValue<double>& SHCoefficients );
00055 
00056     /**
00057      * Destructor.
00058      */
00059     virtual ~WSymmetricSphericalHarmonic();
00060 
00061     /**
00062      * Return the value on the sphere.
00063      * \param theta angle for the position on the unit sphere
00064      * \param phi angle for the position on the unit sphere
00065      *
00066      * \return value on sphere
00067      */
00068     double getValue( double theta, double phi ) const;
00069 
00070     /**
00071      * Return the value on the sphere.
00072      * \param coordinates for the position on the unit sphere
00073      *
00074      * \return value on sphere
00075      */
00076     double getValue( const WUnitSphereCoordinates& coordinates ) const;
00077 
00078     /**
00079      * Returns the used coefficients (stored like in the mentioned 2007 Descoteaux paper).
00080      *
00081      * \return coefficient list
00082      */
00083     const WValue<double>& getCoefficients() const;
00084 
00085     /**
00086      * Returns the coefficients for Schultz' SH base.
00087      *
00088      * \return coefficient list
00089      */
00090     WValue< double > getCoefficientsSchultz() const;
00091 
00092     /**
00093      * Returns the coefficients for the complex base.
00094      *
00095      * \return coefficiend list
00096      */
00097     WValue< std::complex< double > > getCoefficientsComplex() const;
00098 
00099     /**
00100      * Applies the Funk-Radon-Transformation. This is faster than matrix multiplication.
00101      * ( O(n) instead of O(n²) )
00102      *
00103      * \param frtMat the frt matrix as calculated by calcFRTMatrix()
00104      */
00105     void applyFunkRadonTransformation( WMatrix< double > const& frtMat );
00106 
00107     /**
00108      * Return the order of the spherical harmonic.
00109      *
00110      * \return order of SH
00111      */
00112     size_t getOrder() const;
00113 
00114     /**
00115      * Calculate the generalized fractional anisotropy for this ODF.
00116      *
00117      * See: David S. Tuch, "Q-Ball Imaging", Magn. Reson. Med. 52, 2004, 1358-1372
00118      *
00119      * \note this only makes sense if this is an ODF, meaning funk-radon-transform was applied etc.
00120      *
00121      * \param orientations A vector of unit sphere coordinates.
00122      *
00123      * \return The generalized fractional anisotropy.
00124      */
00125     double calcGFA( std::vector< WUnitSphereCoordinates > const& orientations ) const;
00126 
00127     /**
00128      * Calculate the generalized fractional anisotropy for this ODF. This version of
00129      * the function uses precomputed base functions (because calculating the base function values
00130      * is rather expensive). Use this version if you want to compute the GFA for multiple ODFs
00131      * with the same base functions. The base function Matrix can be computed using \see calcBMatrix().
00132      *
00133      * See: David S. Tuch, "Q-Ball Imaging", Magn. Reson. Med. 52, 2004, 1358-1372
00134      *
00135      * \note this only makes sense if this is an ODF, meaning funk-radon-transform was applied etc.
00136      *
00137      * \param B The matrix of SH base functions.
00138      *
00139      * \return The generalized fractional anisotropy.
00140      */
00141     double calcGFA( WMatrix< double > const& B ) const;
00142 
00143     /**
00144     * This calculates the transformation/fitting matrix T like in the 2007 Descoteaux paper. The orientations are given as WVector3d.
00145     * \param orientations The vector with the used orientation on the unit sphere (usually the gradients of the HARDI)
00146     * \param order The order of the spherical harmonics intended to create
00147     * \param lambda Regularization parameter for smoothing matrix
00148     * \param withFRT include the Funk-Radon-Transformation?
00149     * \return Transformation matrix
00150     */
00151     static WMatrix<double> getSHFittingMatrix( const std::vector< WVector3d >& orientations,
00152                                                       int order,
00153                                                       double lambda,
00154                                                       bool withFRT );
00155 
00156     /**
00157     * This calculates the transformation/fitting matrix T like in the 2007 Descoteaux paper. The orientations are given as WUnitSphereCoordinates .
00158     * \param orientations The vector with the used orientation on the unit sphere (usually the gradients of the HARDI)
00159     * \param order The order of the spherical harmonics intended to create
00160     * \param lambda Regularization parameter for smoothing matrix
00161     * \param withFRT include the Funk-Radon-Transformation?
00162     * \return Transformation matrix
00163     */
00164     static WMatrix<double> getSHFittingMatrix( const std::vector< WUnitSphereCoordinates >& orientations,
00165                                                       int order,
00166                                                       double lambda,
00167                                                       bool withFRT );
00168 
00169     /**
00170     * Calculates the base matrix B like in the dissertation of Descoteaux.
00171     * \param orientations The vector with the used orientation on the unit sphere (usually the gradients of the HARDI)
00172     * \param order The order of the spherical harmonics intended to create
00173     * \return The base Matrix B
00174     */
00175     static WMatrix<double> calcBaseMatrix( const std::vector< WUnitSphereCoordinates >& orientations, int order );
00176 
00177     /**
00178     * Calculates the base matrix B for the complex spherical harmonics.
00179     * \param orientations The vector with the used orientation on the unit sphere (usually the gradients of the HARDI)
00180     * \param order The order of the spherical harmonics intended to create
00181     * \return The base Matrix B
00182     */
00183     static WMatrix< std::complex< double > > calcComplexBaseMatrix( std::vector< WUnitSphereCoordinates > const& orientations,
00184                                                                            int order );
00185 
00186     /**
00187     * This calcs the smoothing matrix L from the 2007 Descoteaux Paper "Regularized, Fast, and Robust Analytical Q-Ball Imaging"
00188     * \param order The order of the spherical harmonic
00189     * \return The smoothing matrix L
00190     */
00191     static WMatrix<double> calcSmoothingMatrix( size_t order );
00192 
00193     /**
00194     * Calculates the Funk-Radon-Transformation-Matrix P from the 2007 Descoteaux Paper "Regularized, Fast, and Robust Analytical Q-Ball Imaging"
00195     * \param order The order of the spherical harmonic
00196     * \return The Funk-Radon-Matrix P
00197     */
00198     static WMatrix<double> calcFRTMatrix( size_t order );
00199 
00200    /**
00201      * Calculates a matrix that converts spherical harmonics to symmetric tensors of equal or lower order.
00202      *
00203      * \param order The order of the symmetric tensor.
00204      * \param orientations A vector of at least (orderTensor+1) * (orderTensor+2) / 2 orientations.
00205      *
00206      * \return the conversion matrix
00207      */
00208     static WMatrix< double > calcSHToTensorSymMatrix( std::size_t order, const std::vector< WUnitSphereCoordinates >& orientations );
00209 
00210     /**
00211      * Normalize this SH in place.
00212      */
00213     void normalize();
00214 
00215 protected:
00216 
00217 private:
00218     /** order of the spherical harmonic */
00219     size_t m_order;
00220 
00221     /** coefficients of the spherical harmonic */
00222     WValue<double> m_SHCoefficients;
00223 };
00224 
00225 #endif  // WSYMMETRICSPHERICALHARMONIC_H
 All Classes Namespaces Functions Variables Typedefs Enumerations Enumerator Friends