Developer documentation
Version 3.0.3-105-gd3941f44
Spherical Harmonics

Classes & functions to manage spherical harmonics. More...

Classes

class  MR::Math::SH::Transform< ValueType >
 
class  MR::Math::SH::PrecomputedFraction< ValueType >
 used to speed up SH calculation More...
 
class  MR::Math::SH::PrecomputedAL< ValueType >
 Precomputed Associated Legrendre Polynomials - used to speed up SH calculation. More...
 
class  MR::Math::SH::aPSF< ValueType >
 a class to hold the coefficients for an apodised point-spread function. More...
 

Functions

size_t MR::Math::SH::NforL (int lmax)
 the number of (even-degree) coefficients for the given value of lmax More...
 
size_t MR::Math::SH::index (int l, int m)
 compute the index for coefficient (l,m) More...
 
size_t MR::Math::SH::NforL_mpos (int lmax)
 same as NforL(), but consider only non-negative orders m More...
 
size_t MR::Math::SH::index_mpos (int l, int m)
 same as index(), but consider only non-negative orders m More...
 
size_t MR::Math::SH::LforN (int N)
 returns the largest lmax given N parameters More...
 
template<class MatrixType >
Eigen::Matrix< typename MatrixType::Scalar, Eigen::Dynamic, Eigen::Dynamic > MR::Math::SH::init_transform (const MatrixType &dirs, const int lmax)
 form the SH->amplitudes matrix More...
 
template<class MatrixType >
Eigen::Matrix< typename MatrixType::Scalar, Eigen::Dynamic, Eigen::Dynamic > MR::Math::SH::init_transform_cart (const MatrixType &dirs, const int lmax)
 form the SH->amplitudes matrix More...
 
template<class MatrixType , class VectorType >
void MR::Math::SH::scale_degrees_forward (MatrixType &SH2amp_mapping, const VectorType &coefs)
 scale the coefficients of each SH degree by the corresponding value in coefs More...
 
template<typename MatrixType , class VectorType >
void MR::Math::SH::scale_degrees_inverse (MatrixType &amp2SH_mapping, const VectorType &coefs)
 scale the coefficients of each SH degree by the corresponding value in coefs More...
 
template<typename VectorType >
Eigen::Matrix< typename VectorType::Scalar, Eigen::Dynamic, 1 > MR::Math::SH::invert (const VectorType &coefs)
 invert any non-zero coefficients in coefs More...
 
template<class VectorType >
VectorType::Scalar MR::Math::SH::value (const VectorType &coefs, typename VectorType::Scalar cos_elevation, typename VectorType::Scalar cos_azimuth, typename VectorType::Scalar sin_azimuth, int lmax)
 
template<class VectorType >
VectorType::Scalar MR::Math::SH::value (const VectorType &coefs, typename VectorType::Scalar cos_elevation, typename VectorType::Scalar azimuth, int lmax)
 
template<class VectorType1 , class VectorType2 >
VectorType1::Scalar MR::Math::SH::value (const VectorType1 &coefs, const VectorType2 &unit_dir, int lmax)
 
template<class VectorType1 , class VectorType2 >
VectorType1 & MR::Math::SH::delta (VectorType1 &delta_vec, const VectorType2 &unit_dir, int lmax)
 
template<class VectorType1 , class VectorType2 >
VectorType1 & MR::Math::SH::SH2RH (VectorType1 &RH, const VectorType2 &sh)
 
template<class VectorType >
Eigen::Matrix< typename VectorType::Scalar, Eigen::Dynamic, 1 > MR::Math::SH::SH2RH (const VectorType &sh)
 
template<class VectorType1 , class VectorType2 >
VectorType1 & MR::Math::SH::sconv (VectorType1 &sh, const VectorType2 &RH)
 perform spherical convolution, in place More...
 
template<class VectorType1 , class VectorType2 , class VectorType3 >
VectorType1 & MR::Math::SH::sconv (VectorType1 &C, const VectorType2 &RH, const VectorType3 &sh)
 perform spherical convolution More...
 
template<class MatrixType1 , class VectorType2 >
MatrixType1 & MR::Math::SH::sconv_mat (MatrixType1 &sh, const VectorType2 &RH)
 perform spherical convolution, in place More...
 
template<class VectorType , class UnitVectorType , class ValueType = float>
VectorType::Scalar MR::Math::SH::get_peak (const VectorType &sh, int lmax, UnitVectorType &unit_init_dir, PrecomputedAL< typename VectorType::Scalar > *precomputer=nullptr)
 estimate direction & amplitude of SH peak More...
 
template<class VectorType >
void MR::Math::SH::derivatives (const VectorType &sh, const int lmax, const typename VectorType::Scalar elevation, const typename VectorType::Scalar azimuth, typename VectorType::Scalar &amplitude, typename VectorType::Scalar &dSH_del, typename VectorType::Scalar &dSH_daz, typename VectorType::Scalar &d2SH_del2, typename VectorType::Scalar &d2SH_deldaz, typename VectorType::Scalar &d2SH_daz2, PrecomputedAL< typename VectorType::Scalar > *precomputer)
 computes first and second order derivatives of SH series More...
 
template<class ImageType >
void MR::Math::SH::check (const ImageType &H)
 convenience function to check if an input image can contain SH coefficients More...
 

Variables

const char * MR::Math::SH::encoding_description
 a string containing a description of the SH storage convention More...
 

Detailed Description

Classes & functions to manage spherical harmonics.

Function Documentation

◆ check()

template<class ImageType >
void MR::Math::SH::check ( const ImageType &  H)

convenience function to check if an input image can contain SH coefficients

Definition at line 745 of file SH.h.

◆ delta()

template<class VectorType1 , class VectorType2 >
VectorType1 & MR::Math::SH::delta ( VectorType1 &  delta_vec,
const VectorType2 &  unit_dir,
int  lmax 
)
inline

Definition at line 279 of file SH.h.

◆ derivatives()

template<class VectorType >
void MR::Math::SH::derivatives ( const VectorType &  sh,
const int  lmax,
const typename VectorType::Scalar  elevation,
const typename VectorType::Scalar  azimuth,
typename VectorType::Scalar &  amplitude,
typename VectorType::Scalar &  dSH_del,
typename VectorType::Scalar &  dSH_daz,
typename VectorType::Scalar &  d2SH_del2,
typename VectorType::Scalar &  d2SH_deldaz,
typename VectorType::Scalar &  d2SH_daz2,
PrecomputedAL< typename VectorType::Scalar > *  precomputer 
)
inline

computes first and second order derivatives of SH series

This is used primarily in the get_peak() function.

Definition at line 569 of file SH.h.

◆ get_peak()

template<class VectorType , class UnitVectorType , class ValueType = float>
VectorType::Scalar MR::Math::SH::get_peak ( const VectorType &  sh,
int  lmax,
UnitVectorType &  unit_init_dir,
PrecomputedAL< typename VectorType::Scalar > *  precomputer = nullptr 
)
inline

estimate direction & amplitude of SH peak

find a peak of an SH series using Gauss-Newton optimisation, modified to operate directly in spherical coordinates. The initial search direction is unit_init_dir. If precomputer is not nullptr, it will be used to speed up the calculations, at the cost of a minor reduction in accuracy.

Definition at line 515 of file SH.h.

◆ index()

size_t MR::Math::SH::index ( int  l,
int  m 
)
inline

compute the index for coefficient (l,m)

Definition at line 52 of file SH.h.

◆ index_mpos()

size_t MR::Math::SH::index_mpos ( int  l,
int  m 
)
inline

same as index(), but consider only non-negative orders m

Definition at line 64 of file SH.h.

◆ init_transform()

template<class MatrixType >
Eigen::Matrix< typename MatrixType::Scalar, Eigen::Dynamic, Eigen::Dynamic > MR::Math::SH::init_transform ( const MatrixType &  dirs,
const int  lmax 
)

form the SH->amplitudes matrix

This computes the matrix SHT mapping spherical harmonic coefficients up to maximum harmonic degree lmax onto directions dirs (in spherical coordinates, with columns [ azimuth elevation ]).

Definition at line 82 of file SH.h.

◆ init_transform_cart()

template<class MatrixType >
Eigen::Matrix< typename MatrixType::Scalar, Eigen::Dynamic, Eigen::Dynamic > MR::Math::SH::init_transform_cart ( const MatrixType &  dirs,
const int  lmax 
)

form the SH->amplitudes matrix

This computes the matrix SHT mapping spherical harmonic coefficients up to maximum harmonic degree lmax onto directions dirs (in cartesian coordinates, with columns [ x y z ] ans normalised).

Definition at line 111 of file SH.h.

◆ invert()

template<typename VectorType >
Eigen::Matrix< typename VectorType::Scalar, Eigen::Dynamic, 1 > MR::Math::SH::invert ( const VectorType &  coefs)
inline

invert any non-zero coefficients in coefs

Definition at line 180 of file SH.h.

◆ LforN()

size_t MR::Math::SH::LforN ( int  N)
inline

returns the largest lmax given N parameters

Definition at line 70 of file SH.h.

◆ NforL()

size_t MR::Math::SH::NforL ( int  lmax)
inline

the number of (even-degree) coefficients for the given value of lmax

Definition at line 46 of file SH.h.

◆ NforL_mpos()

size_t MR::Math::SH::NforL_mpos ( int  lmax)
inline

same as NforL(), but consider only non-negative orders m

Definition at line 58 of file SH.h.

◆ scale_degrees_forward()

template<class MatrixType , class VectorType >
void MR::Math::SH::scale_degrees_forward ( MatrixType &  SH2amp_mapping,
const VectorType &  coefs 
)
inline

scale the coefficients of each SH degree by the corresponding value in coefs

Definition at line 147 of file SH.h.

◆ scale_degrees_inverse()

template<typename MatrixType , class VectorType >
void MR::Math::SH::scale_degrees_inverse ( MatrixType &  amp2SH_mapping,
const VectorType &  coefs 
)
inline

scale the coefficients of each SH degree by the corresponding value in coefs

Definition at line 163 of file SH.h.

◆ sconv() [1/2]

template<class VectorType1 , class VectorType2 , class VectorType3 >
VectorType1 & MR::Math::SH::sconv ( VectorType1 &  C,
const VectorType2 &  RH,
const VectorType3 &  sh 
)
inline

perform spherical convolution

perform spherical convolution of SH coefficients sh with response function RH, storing the results in vector C.

Definition at line 349 of file SH.h.

◆ sconv() [2/2]

template<class VectorType1 , class VectorType2 >
VectorType1 & MR::Math::SH::sconv ( VectorType1 &  sh,
const VectorType2 &  RH 
)
inline

perform spherical convolution, in place

perform spherical convolution of SH coefficients sh with response function RH, storing the results in place in vector sh.

Definition at line 333 of file SH.h.

◆ sconv_mat()

template<class MatrixType1 , class VectorType2 >
MatrixType1 & MR::Math::SH::sconv_mat ( MatrixType1 &  sh,
const VectorType2 &  RH 
)
inline

perform spherical convolution, in place

perform spherical convolution of SH coefficients, stored in rows in matrix sh with response function RH, storing the results in place in matrix sh.

Definition at line 367 of file SH.h.

◆ SH2RH() [1/2]

template<class VectorType >
Eigen::Matrix< typename VectorType::Scalar, Eigen::Dynamic, 1 > MR::Math::SH::SH2RH ( const VectorType &  sh)
inline

Definition at line 321 of file SH.h.

◆ SH2RH() [2/2]

template<class VectorType1 , class VectorType2 >
VectorType1 & MR::Math::SH::SH2RH ( VectorType1 &  RH,
const VectorType2 &  sh 
)
inline

Definition at line 308 of file SH.h.

◆ value() [1/3]

template<class VectorType >
VectorType::Scalar MR::Math::SH::value ( const VectorType &  coefs,
typename VectorType::Scalar  cos_elevation,
typename VectorType::Scalar  azimuth,
int  lmax 
)
inline

Definition at line 259 of file SH.h.

◆ value() [2/3]

template<class VectorType >
VectorType::Scalar MR::Math::SH::value ( const VectorType &  coefs,
typename VectorType::Scalar  cos_elevation,
typename VectorType::Scalar  cos_azimuth,
typename VectorType::Scalar  sin_azimuth,
int  lmax 
)
inline

Definition at line 233 of file SH.h.

◆ value() [3/3]

template<class VectorType1 , class VectorType2 >
VectorType1::Scalar MR::Math::SH::value ( const VectorType1 &  coefs,
const VectorType2 &  unit_dir,
int  lmax 
)
inline

Definition at line 268 of file SH.h.

Variable Documentation

◆ encoding_description

const char* MR::Math::SH::encoding_description
extern

a string containing a description of the SH storage convention

This can used directly in the DESCRIPTION field of a command's usage() function.